Guía de administración de webhooks en el sistema externo a Stock & Trace

La siguiente guía es para los equipos técnicos del sistema externo conectado a Stock & Trace.

En este artículo, se tratan los siguientes temas:

• Confirmar la autenticidad de los menajes de Stock & Trace.
• Comunicar mensajes de error en una transacción webhook.

Otros artículos relacionados:

• Explicación sobre comunicación vía webhooks

Confirmar la autenticidad de los mensajes de Stock & Trace

Para asegurar la autenticidad de los mensajes que recibe el sistema externo de Stock & Trace, es fundamental autenticar que provienen realmente de Stock & Trace. Los mensajes se envían mediante solicitudes HTTP POST en formato JSON.

Criterios esenciales:

• Un superadministrador de Stock & Trace debe configurar el webhook y proporcionar el código secreto relacionado para la autenticidad.

Pasos para validar la comunicación proviene de Stock & Trace:

1. Realice un Hash del contenido del cuerpo HTTP recibido de Stock & Trace, utilizando HMAC con el algoritmo SHA256.
2. Use el código secreto proporcionado para generar el HMAC.
3. Comparte el resultado HMAC con el valor en la cabecera HTTP X-StockAndTrace-Signature del mensaje original. Si no coinciden, no confié en la petición recibida.

Comunicar mensajes de error en una transacción webhook

Stock & Trace ofrece una API para que el sistema externo pueda informar sobre errores que impidieron procesar la información correctamente en su sistema. Esto permite que el equipo de bodega tenga visibilidad sobre posible problemas que afectan el proceso.

Ejemplos de errores que pueden comunicarse:

• El sistema externo no acepta las solicitudes de Stock & Trace debido a cambios en su infraestructura o problemas técnicos.
• Fallos en el procesamiento de órdenes causados por información inválida transmitida desde Stock & Trace.

Criterios para comunicar un mensaje de error:

• El sistema externo requiere extraer el ID de transacción del mensaje recibido a través del webhook.

Pasos para comunicar un mensaje de error:

• Al recibir un mensaje vía webhok de Stock & Trace, extraiga el ID de la transacción, que se encuentra bajo transaction.id.
• Utilice el endpoint POST api/v1/external_integrations/transaction/{id}/errors, sustituyendo {id} por el identificador único de la transacción recibido de Stock & Trace.
• En el cuerpo de la petición, envíe un arreglo con los diferentes errores encontrados al validar la información en su sistema.
  • Para mayor detalle sobre la estructura esperada por la API, consulte el mensaje "Webhook - Add errors" en la siguiente colección de Postman.