Fonctionnement des extraits de code dans Automation

Les extraits de code vous permettent d'ajouter votre propre étape JavaScript à un workflow Automation. Utilisez-les lorsque les conditions et actions intégrées ne suffisent pas : pour appeler votre OMS, ERP ou système d'entrepôt, pour calculer un score ou une valeur à partir des données de la commande, ou pour bloquer une commande avant son expédition lorsqu'un système externe l'exige.

Comment ça marche

L'action Run code snippet exécute un extrait de code : une petite fonction JavaScript que vous écrivez une fois et réutilisez dans n'importe quel workflow. Lors de l'exécution du workflow, ShippyPro transmet à l'extrait les données de commande que vous avez sélectionnées, l'exécute dans une sandbox sécurisée et renvoie ses résultats au workflow.

Écrivez l'extrait dans l'onglet Extraits de code d'Automation : le code, les données de commande qu'il lit (entrées), les résultats qu'il renvoie (sorties), les secrets qu'il utilise et les hôtes externes qu'il peut appeler.
Testez-le avec des valeurs d'exemple avant de l'enregistrer.
Soumettez-le pour validation. Chaque version est vérifiée automatiquement avant de pouvoir être exécutée.
Ajoutez-le à un workflow avec l'action Run code snippet, associez ses entrées aux champs de la commande et enregistrez le workflow.

Triggers disponibles

Un workflow contenant l'action Run code snippet peut démarrer avec les triggers suivants :

Commande importée
Étiquette d'expédition créée
Étiquette imprimée
Commande en erreur
Tout autre trigger disponible dans ShippyPro

Écrire un extrait de code

Chaque extrait exporte une fonction asynchrone appelée main. Elle reçoit un event et renvoie un objet contenant 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 } }; }

Entrées

Les entrées sont les champs de la commande que l'extrait lit, par exemple l'ID de commande, le montant total, la devise, le pays de destination, l'adresse ou les articles. Vous donnez un nom à chaque entrée et l'associez à un champ de la commande lorsque vous ajoutez l'étape à un workflow. Dans le code, elles sont disponibles dans event.inputFields. Les articles de la commande arrivent sous forme de liste, chaque article ayant un nom, un SKU, un EAN, une quantité et un poids.

Sorties

Les sorties sont les valeurs renvoyées par l'extrait. Déclarez chacune avec un nom et un type : texte (string), nombre (number), vrai/faux (boolean), date et heure (datetime) ou liste de valeurs autorisées (enum). Les valeurs renvoyées doivent correspondre aux types déclarés.

Vous pouvez utiliser les sorties dans les notes rédigées par les actions suivantes du même workflow, par exemple pour enregistrer l'entrepôt choisi par votre OMS ou la raison pour laquelle une commande a été bloquée.

Secrets

Stockez les clés API et les tokens en tant que secrets, jamais dans le code. Le nom d'un secret utilise des majuscules, des chiffres et des underscores (par exemple OMS_API_KEY). Dans le code, lisez-le depuis event.secrets. Les valeurs des secrets ne sont plus affichées après leur enregistrement.

Appels externes

Les extraits de code peuvent appeler des API externes avec fetch. Pour des raisons de sécurité, un extrait ne peut appeler que les hôtes listés dans ses paramètres (jusqu'à 10, par exemple api.example.com ou *.example.com), et uniquement en HTTPS.

Limites

Limite	Valeur
Durée maximale par exécution	10 secondes
Mémoire	128 Mo
Appels externes par exécution	5, chacun avec un délai d'expiration de 3 secondes
Taille de chaque réponse externe	512 Ko
Hôtes autorisés par extrait	10, HTTPS uniquement
Secrets par extrait	20
Entrées / sorties par extrait	30 / 30
Taille du code	64 Ko
Lignes de log conservées par exécution	200

La sandbox fournit le JavaScript standard (JSON, Math, Date, URL), fetch et console.log. Les timers, l'accès aux fichiers, les modules Node.js et les imports de packages ne sont pas disponibles.

En cas d'échec de l'extrait

Un extrait de code échoue lorsqu'il lève une erreur, dépasse le délai d'exécution ou renvoie des valeurs qui ne correspondent pas à ses sorties. Vous choisissez ce qui arrive à la commande, dans le paramètre If the snippet fails de l'extrait :

Stop the workflow (arrêter le workflow) : la commande reçoit le tag automation-blocked et une note contenant le message d'erreur, afin que votre équipe sache pourquoi elle a été bloquée. Lever une erreur avec un message clair est la façon de bloquer volontairement une commande, par exemple lorsque votre contrôle anti-fraude ou de stock indique qu'elle ne doit pas être expédiée.
Skip this step and continue (ignorer l'étape et continuer) : l'étape est ignorée et le reste du workflow s'exécute.
Retry, then stop the workflow (réessayer, puis arrêter le workflow) : l'étape est relancée plusieurs fois avant l'arrêt du workflow.

Versions et validation

Chaque modification d'un extrait crée une nouvelle version, qui est vérifiée avant de pouvoir être exécutée. Les versions déjà enregistrées ne changent jamais. Un workflow continue d'utiliser la version avec laquelle il a été enregistré : pour passer un workflow à une version plus récente, ouvrez l'étape Run code snippet, sélectionnez la nouvelle version et enregistrez le workflow.

Conseils

Un extrait par branche de workflow. Pour exécuter plusieurs extraits sur la même commande, créez un workflow pour chacun et définissez leurs priorités : les workflows ayant la priorité la plus élevée s'exécutent en premier.
Faites en sorte que vos extraits puissent s'exécuter deux fois sans risque. Un workflow peut s'exécuter à nouveau sur la même commande : vérifiez donc si votre système externe possède déjà la commande avant d'y créer ou modifier quoi que ce soit.
Rédigez des messages d'erreur clairs. Avec Stop the workflow, le message devient la note sur la commande : rédigez-le pour la personne qui le lira.
Loggez ce qui compte. Utilisez console.log pour les valeurs que vous souhaitez vérifier plus tard ; ne loggez jamais de secrets.

Exemples d'utilisation

Envoyez les commandes à votre OMS et enregistrez dans une note l'entrepôt qu'il a choisi.
Évaluez le risque de la commande (valeur, destination, mode de paiement) et bloquez les commandes à haut risque pour vérification.
Confirmez l'expédition à votre OMS ou ERP lorsque l'étiquette est générée.