Comprobaciones propias de archivos de impresión

El diseñador de productos ya comprueba por sí mismo la resolución, el contraste, el margen de seguridad, el solapamiento y el número de colores de impresión. Si tu producción tiene otras reglas, por ejemplo «un logotipo debe medir al menos 15 mm de ancho» o «nada de texto por debajo de 6 mm en estampación en caliente», añades tus propias comprobaciones: en el navegador con JavaScript o en tu servidor mediante un webhook.

Para una regla que debe cumplirse, usa el webhook. Lo ideal es combinar ambos: el navegador muestra el aviso al instante y el servidor lo garantiza.

Comprobación en el navegador

Registras una comprobación mediante la interfaz JavaScript:

Configento.registerDesignCheck('logo-ancho-minimo', (ctx) =>
    ctx.placement && ctx.placement.widthMm < 15
        ? { level: 'block', message: 'El logotipo debe medir al menos 15 mm de ancho.' }
        : null,
    { appliesTo: ['logo'] });

• El nombre consta de minúsculas, dígitos y guiones.
• appliesTo indica los Nombres internos (ID) de las características a las que se aplica. Sin appliesTo, se ejecuta para cada texto propio y cada imagen propia.
• registerDesignCheck devuelve una función que vuelve a dar de baja la comprobación.

Si tu script se ejecuta antes de que se cargue configento.js, define las comprobaciones de antemano:

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

Qué recibe la comprobación

La comprobación se ejecuta con cada cambio y recibe un objeto ctx:

Qué responde la comprobación

• null: todo está bien.
• { level: 'warn', message: '…' }: el aviso aparece junto al campo, pero se puede pedir igualmente.
• { level: 'block', message: '…' }: el aviso aparece junto al campo y el configurador retiene el carrito.
• Una lista de estos resultados si hay varias cosas que no encajan.

Das estilo al aviso con la clase .cfg-design__check; data-configento-level indica si es una advertencia o un bloqueo, y data-configento-check da el nombre de tu comprobación. Consulta Personalizar el diseño. Si una comprobación lanza un error, el configurador la ignora y escribe el error en la consola del navegador.

Comprobación en tu servidor

Con un webhook, tu servidor comprueba cada diseño antes de que llegue al carrito. Así la regla se cumple aunque alguien eluda el navegador.

Configuración

1. En el admin, abre Ajustes → API y allí Webhook de comprobación de archivos de impresión.
2. Introduce la URL del webhook. Solo se permite https a una dirección pública.
3. configento.app genera una Clave de firma (dcw_…). Guárdala en tu servidor. Nueva clave la sustituye.
4. Haz clic en Enviar llamada de prueba. Si tu servidor responde, aparece «El webhook ha respondido.».
5. Decide si debe aplicarse Rechazar el carrito si el webhook no responde (véase más abajo).

La solicitud

Al añadir al carrito, configento.app vuelve a calcular el precio y envía a tu URL, por POST, todos los textos e imágenes propios visibles y rellenados:

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

Cada elemento de fields tiene la misma estructura que ctx en el navegador (mostrado de forma abreviada). Solo box es siempre null en el servidor.

Las cabeceras:

Comprueba la firma antes de confiar en la solicitud, p. ej. 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'] || ''));

Descarta también las solicitudes cuyo momento tenga más de unos minutos de antigüedad.

La respuesta

Tu servidor responde con un estado 2xx y:

{ "findings": [ { "field": "logo", "level": "block", "message": "El logotipo debe medir al menos 15 mm de ancho." } ] }

field es el nombre interno de la característica. Una lista vacía significa que todo está bien.

Tu servidor tiene 2 segundos; configento.app no sigue redirecciones. El resultado vale 5 minutos junto con el precio, y una configuración idéntica no vuelve a preguntar durante ese tiempo.

Requisito en la tienda

El webhook se ejecuta en la comprobación de precio. Si bloquea, la configuración no entra en el carrito y tu cliente ve allí tu mensaje, a partir de estas versiones del plugin:

Con versiones anteriores del plugin el bloqueo también se aplica, pero tu cliente solo ve el mensaje general de que la configuración ya no es válida o de que no se pudo confirmar el precio.

Muestra por tanto tu mensaje también mediante una comprobación en el navegador; así tu cliente lo ve ya mientras diseña.

Solución de problemas

1. La comprobación en el navegador no tiene efecto: ¿es correcto el nombre interno en appliesTo? ¿Se carga el script después de configento.js, o usas window.ConfigentoDesignChecks? Los errores de la comprobación aparecen en la consola del navegador.
2. «El webhook no dio una respuesta utilizable»: tu servidor no responde en 2 segundos, redirige, responde sin 2xx o sin JSON válido.
3. El bloqueo no tiene efecto en la tienda: en Magento la comprobación de precio no está en Enforce. Tu cliente solo ve un mensaje general: el plugin es anterior a las versiones de arriba.
4. La firma no coincide: calcúlala sobre el cuerpo bruto sin modificar de la solicitud, no sobre un JSON recodificado, y comprueba que guardaste la nueva clave tras Nueva clave.

Próximos pasos

• Texto propio en el producto
• Imagen propia en el producto
• Interfaz JavaScript
• Introducción a la API