¿Qué es?
Un Webhook es un servicio que permite lanzar o desplegar notificaciones ante un determinado evento a otro servicio especifico. Recomendamos la implementación de Webhooks si deseas mantener actualizado tu sistema con la información de los pedidos cargados y gestionados en Beetrack. Cada vez que una ruta sea creada, iniciada o finalizada o un pedido cambie de estado se gatillará el envío de información a su sistema. La información se entrega en formato JSON.
¿Qué necesito para implementar webhooks?
Disponer de una URL donde el webhook enviara las notificaciones.
Por razones de seguridad se recomienda usar un sistema de autenticación.
¿Cómo se configura Webhooks?
Debes ingresar a la plataforma Web de Beetrack, sección Ajustes----> Webhooks.
Ingresar la URL donde deseas recibir la información y configurar Headers. Seleccionar los tipos de eventos para los cuales deseas recibir las notificaciones y presionar “guardar”.
Se pueden configurar hasta cuatro (04) URLs distintas.
Headers
Para autentificarnos en tu servicio, es necesario configurar Headers. Deben ir de la siguiente forma: {"Content-Type": "application/json"} ya que la información que enviamos viaja en formato JSON. Para darle más seguridad sería ideal que agregaran un token de autorización. Ejemplo:
Respuestas
Con respecto a la respuesta de Webhooks, si la respuesta es:
RequestTimeout
InternalServerError
BadGateway
ServiceUnavailable
GatewayTimeout
BandwidthLimitExceeded
Se reintentará en cosa de segundos.
En caso que la respuesta no sea ninguna de las anteriores, se reintentará cada una 1 hora.
El máximo de reintentos son 5.
El tiempo máximo que Beetrack espera una respuesta son de 4 segundos.
La configuración de personalización de los webhooks será la siguiente:
En cada acción del evento se podrá previsualizar el json según la información del último despacho que este contiene, [Ejemplo para una Actualización de Ruta]:
Esta previsualización tendrá un selector que permitirá agregar nuevos campos a cada acción
Sin importar la previsualización escogida, al hacer click en “configurar parámetros avanzados” podrán añadir para cualquier acción / evento los campos personalizables.
Una vez seleccionados los parámetros y haciendo click en “Añadir parámetros” luego en la vista se verán:
En caso de deseleccionar uno de los campos nuevos añadidos y luego guardar, este no se verá en el listado bajo la acción, es decir, se mostrarán solo aquellos campos que están activos para ser enviados en los webhooks por acción.
Parámetros
Recibirás los siguientes mensajes en el endpoint configurado de acuerdo al tipo de actualización:
Rutas
1. Actualización: Cuando se crea una ruta o actualiza una ruta.
2. Comienzo: Cuando una ruta es iniciada.
3. Término: Cuando una ruta es finalizada.
Despachos
1. Actualización: Se gatilla cuando se registra algún cambio de estado. Ejemplo:
a. Cuando se crea un despacho en estado pendiente.
b. Cuando se gestiona el despacho
Se gatilla cuando una guía cambia de estado, en el caso de la gestión te entregaremos los datos de la orden, estado, sub estados, ítems entregados y la información del formulario completado por el usuario móvil al momento de completar la gestión.
{
"resource":"dispatch",
"event":"update",
"account_name":"prueba",
"account_id":1032,
"guide":"20200630-1",
"identifier":"20200630-1",
"route_id":7668595,
"dispatch_id":137690247,
"truck_identifier":"VEH001",
"status":2,
"substatus":"Entregado 2",
"substatus_code":"21",
"contact_identifier":"96.003.283-6",
"contact_phone":"998790989",
"contact_name":"Boxman Ltda",
"contact_email":"administracion@empresa.com",
"contact_address":"San Francisco 1401, Santiago, Santiago",
"tags":[
],
"is_pickup":false,
"is_trunk":false,
"locked":false,
"items":[
{
"id":221491596,
"name":"iPhone",
"description":"iPhone",
"quantity":5,
"original_quantity":5,
"delivered_quantity":5,
"code":"IPH-01",
"extras":[
]
}
],
"groups":[
],
"arrived_at":"2020-06-30 19:22:41-0400",
"waypoint":{
"latitude":"-33.455053",
"longitude":"-70.700805"
},
"evaluation_answers":[
{
"_id":{
"$oid":"5cd2fa0d620c840cfd0d0a43"
},
"cast":"single_choice",
"code":"69d42a00-f744-0136-379d-06fba2ec54bc",
"name":"¿Quien Recibe?",
"value":"Cliente"
},
{
"_id":{
"$oid":"5cd2fa0d620c840cfd0d0a44"
},
"cast":"text",
"code":"57385bd0-f744-0136-9881-02b061a451dc",
"name":"Nombre y Apellido de quien recibe:",
"value":"yo"
},
{
"cast":"photo",
"code":"9f85a160-9159-0137-3209-02ee3848bc34",
"name":"FOTOGRAFIA",
},
{
"_id":{
"$oid":"5cd2fa0d620c840cfd0d0a45"
},
"cast":"email",
"code":"06662f50-009e-0137-bfe5-066bf56665d4",
"name":"Correo de quien recibe",
"value":"c@c.cl"
},
{
"_id":{
"$oid":"5cd2fa0d620c840cfd0d0a46"
},
"cast":"multiple_choice",
"code":"90414ac0-009e-0137-e575-06fba2ec54bc",
"name":"Forma de Pago",
"value":"Debito"
},
{
"_id":{
"$oid":"5cd2fa0d620c840cfd0d0a47"
},
"cast":"currency",
"code":"d3fd0d40-009e-0137-04f4-02dc6ac23cb4",
"name":"¿Cuanto fue el monto a cancelar?",
"value":"1"
},
{
"_id":{
"$oid":"5cd2fa0d620c840cfd0d0a48"
},
"cast":"signature",
"code":"5739e5c0-f744-0136-9881-02b061a451dc",
"name":"Firma del cliente",
}
]
}
2. En ruta desde el móvil: Cuando el usuario móvil crea una ruta y agrega los despachos.
Ordenes
1. Creación: Se gatilla cuando se crea una orden.
Encuestas de satisfacción
Son mensajes que se envían cuando el cliente completa la encuesta de satisfacción, para obtener la información completa hay que seleccionar los dos eventos:
1. Creación: Cuando el cliente hace click en el link de la encuesta de satisfacción enviada por email o SMS.
2. Actualización: Cuando el cliente completa la encuesta evaluando la entrega para los parámetros: envío, servicio, producto y deja algún comentario. Si el cliente vuelve a llenar la encuesta se enviará nuevamente con la información de la evaluación actualizada.
Ventajas de implementar Webhooks
Al activar webhooks en Beetrack podrás:
Recibir notificaciones a determinados eventos.
Mantener tu sistema actualizado con la información de Beetrack en tiempo real.
Evitar sobrepasar el límite de requests establecido por el API de Beetrack. manera constante hasta que cierta acción sea realizada.
Procesar los datos como quieras y realizar tus propios desarrollos a partir de la información de tus gestiones.
Ante cualquier duda cuenten con todo nuestro apoyo, puedes escribirnos a soporte@dispatchtrack.com
Video de como crearlo