Cómo funcionan los fragmentos de código en Automation

Los fragmentos de código te permiten añadir tu propio paso de JavaScript a un workflow de Automation. Úsalos cuando las condiciones y acciones integradas no sean suficientes: para llamar a tu OMS, ERP o sistema de almacén, para calcular una puntuación o un valor a partir de los datos del pedido, o para detener un pedido antes de su envío cuando un sistema externo así lo indique.

Cómo funciona

La acción Run code snippet ejecuta un fragmento de código: una pequeña función de JavaScript que escribes una vez y reutilizas en cualquier workflow. Cuando se ejecuta el workflow, ShippyPro pasa al fragmento los datos del pedido que has seleccionado, lo ejecuta en un sandbox seguro y devuelve sus resultados al workflow.

1. Escribe el fragmento en la pestaña Fragmentos de código de Automation: el código, los datos del pedido que lee (entradas), los resultados que devuelve (salidas), los secretos que usa y los hosts externos a los que puede llamar.
2. Pruébalo con valores de ejemplo antes de guardarlo.
3. Envíalo a revisión. Cada versión se comprueba automáticamente antes de que pueda ejecutarse.
4. Añádelo a un workflow con la acción Run code snippet, asigna sus entradas a los campos del pedido y guarda el workflow.

Triggers disponibles

Un workflow con la acción Run code snippet puede iniciarse con estos triggers:

• Nuevo pedido importado
• Etiqueta de envío creada
• Etiqueta impresa
• Pedido con error
• Cualquier otro trigger disponible en ShippyPro

Escribir un fragmento de código

Cada fragmento exporta una función asíncrona llamada main. Recibe un event y devuelve un objeto con outputFields:

export async function main(event) {   const { orderId, orderTotal, destinationCountry } = event.inputFields;   const { MY_API_KEY } = event.secrets;    const res = await fetch('https://api.example.com/orders/check', {     method: 'POST',     headers: { 'content-type': 'application/json', 'x-api-key': MY_API_KEY },     body: JSON.stringify({ orderId, orderTotal, destinationCountry }),   });    if (!res.ok) {     throw new Error(`Check failed: HTTP ${res.status}`);   }    const { approved, reason } = await res.json();   return { outputFields: { approved, reason } }; }

Entradas

Las entradas son los campos del pedido que lee el fragmento, por ejemplo el ID del pedido, el total, la moneda, el país de destino, la dirección o los artículos. Das un nombre a cada entrada y la asignas a un campo del pedido al añadir el paso a un workflow. En el código están disponibles en event.inputFields. Los artículos del pedido llegan como una lista, en la que cada artículo tiene nombre, SKU, EAN, cantidad y peso.

Salidas

Las salidas son los valores que devuelve el fragmento. Declara cada una con un nombre y un tipo: texto (string), número (number), verdadero/falso (boolean), fecha y hora (datetime) o una lista de valores permitidos (enum). Los valores que devuelvas deben coincidir con los tipos declarados.

Puedes usar las salidas en las notas que escriben las acciones posteriores del mismo workflow, por ejemplo para guardar el almacén que eligió tu OMS o el motivo por el que se detuvo un pedido.

Secretos

Guarda las claves API y los tokens como secretos, nunca en el código. El nombre de un secreto usa mayúsculas, números y guiones bajos (por ejemplo OMS_API_KEY). En el código, léelo desde event.secrets. Los valores de los secretos no se vuelven a mostrar después de guardarlos.

Llamadas externas

Los fragmentos de código pueden llamar a API externas con fetch. Por seguridad, un fragmento solo puede llamar a los hosts que indiques en su configuración (hasta 10, por ejemplo api.example.com o *.example.com), y solo mediante HTTPS.

Límites

El sandbox ofrece JavaScript estándar (JSON, Math, Date, URL), fetch y console.log. Los temporizadores, el acceso a archivos, los módulos de Node.js y la importación de paquetes no están disponibles.

Cuando el fragmento falla

Un fragmento de código falla cuando lanza un error, supera el tiempo de espera o devuelve valores que no coinciden con sus salidas. Tú eliges qué ocurre con el pedido, en el ajuste If the snippet fails del fragmento:

• Stop the workflow (detener el workflow): el pedido recibe el tag automation-blocked y una nota con el mensaje de error, para que tu equipo vea por qué se detuvo. Lanzar un error con un mensaje claro es la forma de detener un pedido a propósito, por ejemplo cuando tu control antifraude o de stock indica que no debe enviarse.
• Skip this step and continue (omitir el paso y continuar): el paso se omite y se ejecuta el resto del workflow.
• Retry, then stop the workflow (reintentar y después detener el workflow): el paso se reintenta varias veces antes de que se detenga el workflow.

Versiones y revisión

Cada vez que modificas un fragmento guardas una nueva versión, que se revisa antes de poder ejecutarse. Las versiones ya guardadas nunca cambian. Un workflow sigue usando la versión con la que se guardó: para pasar un workflow a una versión más reciente, abre el paso Run code snippet, selecciona la nueva versión y guarda el workflow.

Consejos

• Un fragmento por rama del workflow. Para ejecutar varios fragmentos sobre el mismo pedido, crea un workflow para cada uno y define sus prioridades: los workflows con mayor prioridad se ejecutan primero.
• Haz que tus fragmentos puedan ejecutarse dos veces sin problemas. Un workflow puede volver a ejecutarse sobre el mismo pedido, así que comprueba si tu sistema externo ya tiene el pedido antes de crear o modificar algo en él.
• Escribe mensajes de error claros. Con Stop the workflow, el mensaje se convierte en la nota del pedido, así que escríbelo pensando en quien lo leerá.
• Registra lo importante. Usa console.log para los valores que quieras revisar más tarde; nunca registres secretos.

Ejemplos de uso

• Envía los pedidos a tu OMS y guarda en una nota el almacén que eligió.
• Calcula el riesgo del pedido (valor, destino, método de pago) y detén los pedidos de alto riesgo para revisarlos.
• Confirma el envío a tu OMS o ERP cuando se genere la etiqueta.