Para evolucionar las modificaciones de pedidos en la plataforma VTEX, estamos lanzando Modificar pedido (Beta), una solución mucho más completa, versátil y que proporciona una nueva experiencia en el Admin VTEX.

Después de las interacciones entre nuestro equipo de ingenieros y los clientes y partners que ya se habían unido a la versión beta, hemos creado este contenido que incluye buenas prácticas de implementación y dudas frecuentes. Nuestro objetivo es que los próximos clientes y partners que comiencen a utilizar Modificar pedido (Beta) tengan este material de apoyo a su disposición.

El artículo se organiza de la siguiente manera:

• Adaptación en distintos casos de uso
• Modificaciones en el cuerpo de los requests
• Requests con errores y fallos
• Preguntas frecuentes

Las siguientes secciones presentan los principales casos de uso de Modificar pedido (Beta) y sus respectivas recomendaciones.

Modificar pedido (Beta) utiliza nuevas plantillas para los emails transaccionales (Message Center) que se ajustan a las funcionalidades innovadoras de la solución.

Para personalizar una plantilla de email en el Admin VTEX, copia y pega el siguiente link en tu navegador sustituyendo {nombreDeCuenta} por el nombre de cuenta de tu tienda, y luego pulsa Enter:

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

Las tiendas que utilizan la versión actual de la funcionalidad de modificación de pedidos tendrán acceso inmediato a las interfaces actualizadas de Modificar pedido (Beta) en el Admin VTEX una vez que el equipo de VTEX instale la nueva solución. Esto incluye una nueva gestión y comunicación de Mi cuenta y de plantillas de emails transaccionales.

Las tiendas que utilizan nuestras API deben asegurarse de que la implementación en la integración siga la nueva arquitectura de la funcionalidad.

En Modificar pedido (Beta), el endpoint Create order change funciona de forma asíncrona y el usuario o integración que realiza el request recibe un requestId de la plataforma, que se trata de un identificador único para dar seguimiento a la operación de modificación del pedido. Este identificador luego se utilizará en determinados endpoints. Todos los endpoints de Modificar pedido (Beta) son:

• 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

Después de modificar el pedido utilizando el endpoint Create order change, el integrador puede utilizar varias alternativas para los nuevos requests a los endpoints de Modificar pedido (Beta):

• Polling: baja complejidad.
• Preview: mediana complejidad.

La siguiente tabla muestra cada una:

Tipo de flujo	Cómo funciona
Polling Baja complejidad	Después de la operación de modificación del pedido se genera un código único que la identifica, requestId, y que permite dar seguimiento a los detalles del request a través del endpoint Get change details. Tras la modificación del pedido, la propiedad del cuerpo de respuesta finished pasa a tener el valor true en este endpoint. Además, Get change details también se puede utilizar para obtener información sobre fallos y errores que dieron lugar a la cancelación de la operación de modificación del pedido, según se describe en la sección Requests con errores y fallos.
Preview Mediana complejidad	Antes de enviar un request a Create order change, la integración tiene la opción de obtener una vista previa que produce un cuerpo de respuesta exactamente igual al del request de modificación. Para ello, solo hay que utilizar el mismo cuerpo de request en el request enviado al endpoint Preview order change. Esta vista previa es una simulación de la modificación y no genera efectos reales de modificar el pedido. El uso de Preview order change es útil para obtener los valores totales asociados a la modificación del pedido en cuestión y también para validar los detalles del requests con un cuerpo de request válido. Tras recibir una respuesta de éxito 200 OK para obtener la vista previa de la modificación, la integración puede proceder con el request a Create order change para modificar el pedido. Luego, puedes adaptar la integración a escenarios tales como: Creación optimista: los datos de las validaciones obtenidas con la simulación de la modificación cubren la mayor parte de los casos de éxito 200 OK. Implementación de polling: mencionado anteriormente.

Modificar pedido (Beta) mantiene algunos de los atributos de la solución anterior, sin embargo, posee otros que fueron creados o transformados, tanto en nombre como funcionamiento. Los principales cambios se describen de la siguiente forma:

• Valores manuales
• Agregar y remover ítems
• Atributos obligatorios y opcionales de los ítems
• Responsabilidad del usuario en la automatización del sistema

• Antes: los campos discountValue y incrementValue definían el valor de la modificación del pedido como disminución o incremento del valor, respectivamente. El usuario calculaba el valor de la modificación y el resultado se sumaba o restaba del valor total del pedido mediante estos campos.

  Ejemplo: en un pedido de 100 USD que se debe modificar para agregar un ítem de 50 USD, el usuario enviaba incrementValue con el valor de 50 USD y el sistema calculaba el total del pedido como 150 USD. Si el usuario deseaba conceder un descuento de 30 USD al cliente en la modificación, tenía que enviar un discountValue con el valor de 30 USD para que el total del pedido fuera 120 USD.

• Ahora: los nuevos campos manualDiscountValue y manualIncrementValue definen valores manuales adicionales que se suman o restan del costo total del pedido, independientemente de las modificaciones que se estén realizando. Como el sistema calcula el resultado de las modificaciones automáticamente (considerando el precio y condiciones de finalización de compra), el usuario puede incrementar o disminuir los valores utilizando los campos mencionados.

  Ejemplo: en un pedido de 100 USD que debe modificarse para agregar un ítem de 50 USD, tras agregar el ítem, el sistema calcula automáticamente el incremento de 50 USD del valor y el usuario no tiene que enviarlo manualmente. El resultado del valor total del pedido será 150 USD. Si el usuario desea conceder un descuento de 30 USD al cliente en la modificación, solo tiene que enviar el campo manualDiscountValue con el valor de 30 USD y el valor total del pedido será 120 USD.

• Antes: los atributos utilizados para agregar y remover ítems del pedido eran los arreglos itemsAdded y itemsRemoved que contenían objetos de ítems con los campos id, price y quantity.
• Ahora: los atributos para agregar y remover ítems del pedido son los objetos add y remove que contienen un nuevo nivel que define un objeto para cada ítem a través del arreglo items.

Ejemplo de cómo remover ítems en Modificar pedido (Beta):

Los ítems del cuerpo del request necesitan menos atributos obligatorios que antes: id y quantity. Los demás atributos se obtienen del pedido o del sistema Catálogo.

Existen otros campos que pueden ajustarse para sobrescribir la información de un ítem que se está modificando, en caso de ser necesario agregar o modificar ítems ya existentes. Los campos opcionales son price, unitMultiplier y measurementUnit. El sistema no tiene en cuenta ningún otro campo enviado en el request.

• Antes: el usuario era responsable de calcular el valor que se iba a modificar en el pedido. Enviaba dicho valor en el atributo discountValue o incrementValue, dependiendo de si era un aumento o disminución de precio.
• Ahora: el sistema es responsable de proporcionar la información de los ítems y automáticamente calcula el valor final del pedido con la modificación. En otras palabras, el usuario ahora informa lo mínimo necesario y no tiene que calcular el valor final del pedido, lo que reduce las posibilidades de error.

Cuando se produce un error o fallo en el request de Modificar pedido (Beta), se puede obtener la información del procesamiento a través del endpoint Get change details mediante el atributo logs.

Ejemplo de logs con error de procesamiento:

El sistema automáticamente reintenta el procesamiento de cada fallo (errores no tratados). Si los reintentos no funcionan, se cancela el request de modificación. El motivo del error se puede obtener utilizando Get change details mediante el atributo cancellationData.

Si el origen del error es incumplimiento de las reglas de validación del request por parte del usuario, la operación se cancela automáticamente y no se realicen nuevos intentos de procesamiento. En este caso, el motivo del error también se comunica a través de cancellationData.

Ejemplo de objeto cancellationData: la modificación de precio solicitada en el request es mayor que el valor límite configurado para la cancelación de pedidos.

Esta sección presenta dudas comunes de los clientes y partners que utilizan Modificar pedido (beta):

1 - ¿Cómo puedo sobrescribir el precio de un ítem específico?

2 - ¿Cómo puedo saber y cambiar el valor total antes de modificar el pedido?

3 - ¿Tengo que informar el precio de envío o se recalcula automáticamente?

4 - ¿Cómo funcionan las promociones en Modificar pedidos (Beta)?

5 - ¿Qué debo hacer cuando el request devuelve el status canceling o canceled?

Para sobrescribir el precio de un ítem específico, puedes aplicarle un valor manual al ítem al mismo tiempo que se modifica la cantidad.

En el endpoint Create order change, el atributo price tiene la misma función que el flujo de finalización de pedidos y hace referencia al precio nominal del ítem. Por ejemplo, en un pedido que contiene un ítem pesable, como una manzana, price es el precio por kilo de la manzana.

Ejemplo de cómo sobrescribir el precio de un ítem pesable:

El endpoint Preview order change permite al usuario simular el resultado de la modificación del pedido que se desea realizar mediante Create order change, ya que utiliza el mismo cuerpo de request y proporciona el mismo cuerpo de respuesta pero sin modificar el pedido. totalChangeValue es el atributo que informa el valor total que se está modificando en el pedido, ya sea un incremento (por ej.: cargo o ítem adicional) o disminución (por ej.: reducción manual del valor o remover un ítem).

Si deseas que la integración manipule la variación del valor del pedido modificado, puedes utilizar el mismo cuerpo de request que se usa en Preview order change en un request a Create order change, incrementando o disminuyendo el valor de los campos manualIncrementValue y manualDiscountValue, respectivamente.

Cuando se producen cambios en la cantidad, tamaño o peso de los ítems, el costo de envío se recalcula automáticamente y el valor se suma al nuevo valor total del pedido.

La regla de cálculo del nuevo costo de envío sigue las mismas condiciones aplicadas en la finalización del pedido.

Al modificar el pedido se aplican automáticamente las mismas promociones y cargos que eran válidos para los ítems cuando se finalizó la compra. No se recalculan nuevas promociones y cargos en las condiciones del pedido modificado.

Ejemplo: una tienda tenía una promoción de "Paga 2 y lleva 3", pero el cliente solo compró 2 ítems y no pudo beneficiarse del descuento. Cuando el cliente solicita que se agregue un ítem adicional a su pedido, ahora tiene 3 ítems, pero la promoción no se aplica porque no se aplicó en el pedido original.

Para informar la promoción de un ítem al modificar el pedido, puedes hacerlo manualmente con Create order change mediante el atributo priceTags. Este es el comportamiento predeterminado de la plataforma.

Ejemplo de un ítem con promociones aplicadas en el pedido original:

En este ejemplo, se utilizó la tag de descuento manual DISCOUNT@MANUALPRICE. La tag equivalente para cargos manuales sería TAX@MANUALPRICE. El endpoint Create order change también puede utilizar el atributo priceTag de una promoción existente y cambiar el valor de la modificación del pedido.

Los status canceling y canceled significan que la modificación del pedido no se procesó correctamente, los cambios no se aplicaron al pedido y el usuario puede ignorar el intento. Los fallos y errores pueden deberse a:

• El usuario no cumplió las reglas de validación del request.
• El sistema excedió el número de intentos de reprocesamiento automático.
• Otros fallos de procesamiento del sistema.

La recomendación general es investigar el origen del error y comprobar el cuerpo del request que se está enviando a través del endpoint Create order change o Preview order change. Más información en la sección Requests con errores y fallos.

Help Center	Developer Portal
Modificar pedidos en el Admin VTEX: Cómo funciona Modificar pedido (Beta) Cómo modificar pedidos (Beta)	Modificar pedidos vía API: Create order change Preview order change Get order change details Get order change history Retry order change Cancel order change