Contrôles personnalisés des fichiers d'impression

Le concepteur de produits vérifie déjà de lui-même la résolution, le contraste, la marge de sécurité, le chevauchement et le nombre de couleurs d'impression. Si votre production a d'autres règles, par exemple « un logo doit mesurer au moins 15 mm de large » ou « pas de texte de moins de 6 mm en dorure à chaud », vous ajoutez vos propres contrôles : dans le navigateur avec JavaScript ou sur votre serveur via un webhook.

Pour une règle qui doit s'appliquer, utilisez le webhook. Idéalement, combinez les deux : le navigateur affiche la remarque immédiatement, le serveur garantit le respect de la règle.

Contrôle dans le navigateur

Vous enregistrez un contrôle via l'interface JavaScript :

Configento.registerDesignCheck('logo-largeur-min', (ctx) =>
    ctx.placement && ctx.placement.widthMm < 15
        ? { level: 'block', message: 'Le logo doit mesurer au moins 15 mm de large.' }
        : null,
    { appliesTo: ['logo'] });

• Le nom se compose de minuscules, de chiffres et de tirets.
• appliesTo indique les Noms internes (ID) des caractéristiques concernées. Sans appliesTo, le contrôle s'exécute pour chaque texte et chaque image personnalisés.
• registerDesignCheck renvoie une fonction qui désenregistre le contrôle.

Si votre script s'exécute avant le chargement de configento.js, définissez les contrôles à l'avance :

window.ConfigentoDesignChecks = {
    'logo-largeur-min': [check, { appliesTo: ['logo'] }],
};

Ce que reçoit le contrôle

Le contrôle s'exécute à chaque modification et reçoit un objet ctx :

Ce que répond le contrôle

• null : tout est en ordre.
• { level: 'warn', message: '…' } : la remarque apparaît au niveau du champ, la commande reste possible.
• { level: 'block', message: '…' } : la remarque apparaît au niveau du champ et le configurateur retient le panier.
• Une liste de tels résultats si plusieurs points ne conviennent pas.

Vous mettez en forme la remarque avec la classe .cfg-design__check ; data-configento-level indique s'il s'agit d'un avertissement ou d'un blocage, data-configento-check donne le nom de votre contrôle. Voir Personnaliser le design. Si un contrôle lève une erreur, le configurateur l'ignore et écrit l'erreur dans la console du navigateur.

Contrôle sur votre serveur

Avec un webhook, votre serveur contrôle chaque conception avant qu'elle n'arrive dans le panier. Ainsi, la règle tient même si quelqu'un contourne le navigateur.

Configuration

1. Dans l'admin, ouvrez Paramètres → API, puis Webhook de contrôle des fichiers d'impression.
2. Saisissez l'URL du webhook. Seul https vers une adresse publique est autorisé.
3. configento.app génère une Clé de signature (dcw_…). Enregistrez-la sur votre serveur. Nouvelle clé la remplace.
4. Cliquez sur Envoyer un appel de test. Si votre serveur répond, « Le webhook a répondu. » s'affiche.
5. Décidez si Refuser le panier si le webhook ne répond pas doit s'appliquer (voir ci-dessous).

La requête

Lors de l'ajout au panier, configento.app recalcule le prix et envoie à votre URL, par POST, tous les textes et images personnalisés visibles et remplis :

{
  "event": "design_check",
  "component_id": "10000021",
  "locale": "fr_FR",
  "fields": [ { "characteristic": { "key": "logo", "type": "customimage" }, "placement": { "widthMm": 12.4, "dpi": 310 } } ]
}

Chaque élément de fields a la même structure que ctx dans le navigateur (présenté de façon abrégée). Seul box vaut toujours null sur le serveur.

Les en-têtes :

Vérifiez la signature avant de faire confiance à la requête, p. ex. en Node.js :

const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.CONFIGENTO_DCW_SECRET)
    .update(req.headers['x-configento-timestamp'] + '.' + rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-configento-signature'] || ''));

Rejetez aussi les requêtes dont l'horodatage date de plus de quelques minutes.

La réponse

Votre serveur répond avec un statut 2xx et :

{ "findings": [ { "field": "logo", "level": "block", "message": "Le logo doit mesurer au moins 15 mm de large." } ] }

field est le nom interne de la caractéristique. Une liste vide signifie que tout est en ordre.

Votre serveur dispose de 2 secondes ; configento.app ne suit pas les redirections. Le résultat est valable 5 minutes avec le prix, et une configuration identique ne déclenche pas de nouvelle requête pendant ce temps.

Prérequis dans la boutique

Le webhook s'exécute dans le contrôle du prix. S'il bloque, la configuration n'est pas ajoutée au panier et votre client y voit votre message, à partir de ces versions du plugin :

Avec des versions plus anciennes du plugin, le blocage s'applique aussi, mais votre client ne voit que le message général indiquant que la configuration n'est plus valide ou que le prix n'a pas pu être confirmé.

Affichez donc aussi votre message via un contrôle dans le navigateur ; votre client le voit alors dès la conception.

Dépannage

1. Le contrôle dans le navigateur n'a aucun effet : le nom interne dans appliesTo est-il correct ? Le script est-il chargé après configento.js, ou utilisez-vous window.ConfigentoDesignChecks ? Les erreurs du contrôle figurent dans la console du navigateur.
2. « Le webhook n'a pas donné de réponse exploitable » : votre serveur ne répond pas dans les 2 secondes, redirige, répond sans statut 2xx ou sans JSON valide.
3. Le blocage n'a aucun effet dans la boutique : dans Magento, le contrôle du prix n'est pas réglé sur Enforce. Votre client ne voit qu'un message général : le plugin est plus ancien que les versions ci-dessus.
4. La signature ne correspond pas : calculez-la sur le corps brut inchangé de la requête, pas sur un JSON réencodé, et vérifiez que vous avez enregistré la nouvelle clé après Nouvelle clé.

Étapes suivantes

• Texte personnalisé sur le produit
• Image personnalisée sur le produit
• Interface JavaScript
• Introduction à l'API