Servicio de Notificaciones de Cambios de Estado - Webhook
Nuestra API cuenta con un servicio de notificaciones de cambio de estados de un viaje/envío creado, el cual notifica al usuario del cambio de estado de un viaje en curso vía Webhook.
Creación del Webhook
Para crear un webhook, primero es necesario definir una URL de destino. Esta URL es el punto de conexión al cual el servidor enviará los datos mediante una solicitud HTTP POST cada vez que ocurra el evento que el webhook está monitoreando. En este caso, cambios de estado de un viaje.
La configuración del webhook se realiza generalmente a través del módulo de credenciales del panel corporativo de Ridery para Empresas. Aquí deberás proporcionar la URL (válida) del endpoint que has preparado para recibir los datos del webhook.
Ejemplo de Datos Recibidos
Una vez que el webhook esté configurado y el evento monitoreado ocurra, recibirás los datos en el cuerpo (body) de la solicitud POST. Estos datos estarán en formato JSON y contienen información detallada sobre el estado de un viaje en particular.
Ejemplo:
{
"_id": "64729e1f8c9b652308de2347",
"unique_id": "123456",
"content": "_ID: 64729e1f8c9b652308de2347; TRIP ID: 123456; TRIP_STATUS: DRIVER_ARRIVED",
"trip_status": "DRIVER_ARRIVED",
"total": 5.5,
"created_at": "2024-10-09T12:34:56Z", // UTC (0)
"provider": {
"_id": "507f1f77bcf86cd799439011",
"unique_id": "78910",
"first_name": "John",
"last_name": "Snow",
"phone": "4241112233",
"email": "[email protected]",
"vehicle_detail": {
"type": "Sedan",
"brand": "Toyota",
"model": "Camry",
"color": "White",
"passing_year": 2020,
"plate_no": "ABC1234"
},
"provider_previous_location": [40.712776, -74.005974],
"provider_location": [40.712776, -74.005974]
}
}| Campo | Tipo de Dato | Descripción | Ejemplo |
|---|---|---|---|
_id | string | ID único del viaje. | "64729e1f8c9b652308de2347" |
unique_id | string | Identificador único del viaje. | "TRIP123456" |
content | string | Descripción del viaje con ID y estado del viaje. | "TRIP ID: TRIP123456; TRIP_STATUS: completed" |
trip_status | string | Estado actual del viaje (e.g., pending, completed). | "completed" |
total | number | Total del costo del viaje. | 150.75 |
created_at | string (ISO) | Fecha y hora de creación del viaje en formato ISO8601 UTC 0. | "2024-10-09T12:34:56Z" |
provider._id | string | ID único del proveedor (conductor). | "507f1f77bcf86cd799439011" |
provider.unique_id | string | Identificador único del proveedor. | "PROV78910" |
provider.first_name | string | Nombre del proveedor. | "John" |
provider.last_name | string | Apellido del proveedor. | "Doe" |
provider.phone | string | Número de teléfono del proveedor. | "+1234567890" |
provider.email | string | Correo electrónico del proveedor. | "[email protected]" |
provider.vehicle_detail.type | string | Tipo de vehículo del proveedor. | "Sedan" |
provider.vehicle_detail.brand | string | Marca del vehículo. | "Toyota" |
provider.vehicle_detail.model | string | Modelo del vehículo. | "Camry" |
provider.vehicle_detail.color | string | Color del vehículo. | "White" |
provider.vehicle_detail.passing_year | number | Año de registro del vehículo. | 2020 |
provider.vehicle_detail.plate_no | string | Número de placa del vehículo. | "ABC1234" |
provider.provider_previous_location.lat | number | Latitud de la ubicación previa del proveedor. | 40.712776 |
provider.provider_previous_location.lng | number | Longitud de la ubicación previa del proveedor. | -74.005974 |
provider.provider_location.lat | number | Latitud de la ubicación actual del proveedor. | 40.730610 |
provider.provider_location.lng | number | Longitud de la ubicación actual del proveedor. | -73.935242 |
Estados Disponibles
| Estado | Descripción |
|---|---|
| DRIVER_ACCEPTED_TRIP | El conductor ha aceptado el envío/viaje. |
| DRIVER_IN_ROUTE | El conductor está en ruta hacia la ubicación de recogida. |
| DRIVER_ARRIVED | El conductor ha llegado a la ubicación de recogida. |
| DRIVER_STARTED_TRIP | El envío/viaje ha comenzado. |
| DRIVER_COMPLETED_TRIP | El envío/viaje se ha completado exitosamente. |
| DRIVER_NOT_FOUND_CANCELLED_TRIP | No se encontró conductor, el envío/viaje ha sido cancelado. |
| ADMIN_CANCELLED_TRIP | El envío/viaje fue cancelado por un administrador. |
| CORPORATE_CANCELLED_TRIP | El envío/viaje fue cancelado por un corporate. |
| CANCELLED_TRIP | El envío/viaje fue cancelado. |
| RECREATED_TRIP | El envío/viaje fue recreado por un admin . |
RECREATED_TRIP
Un viaje recreado pudiere ocurrir en Ridery cuando un viaje original ha sido cancelado debido a razones operacionales. Ejemplos de estas situaciones no comunes incluyen:
- Los conductores no aceptan el viaje, lo que lleva a su cancelación.
- No hay conductores disponibles en el área en ese momento.
- Surge una eventualidad durante el traslado que interrumpe el viaje.
En estos casos, un administrador de Ridery tiene la capacidad de recrear el viaje, generando uno nuevo a partir del original, con el fin de asegurar que el servicio se complete exitosamente.
Tip
En este estado tenemos un payload de body diferente
{
"content": "RECREATED_TRIP: father_trip_id: ${fatherTripId}; son_trip_id: ${sonTripId};",
"trip_status": "RECREATED_TRIP",
"father_trip_id": "64729e1f8c9b652308de2348",
"son_trip_id": "64729c1f8c9b652308de2348"
}| Campo | Tipo de Dato | Descripción | Ejemplo |
|---|---|---|---|
content | string | Descripción de la recreación del viaje, incluyendo los IDs del padre e hijo. | "RECREATED_TRIP: father_trip_id: 64729e1f8c9b652308de2348; son_trip_id: 64729c1f8c9b652308de2348;" |
trip_status | string | Estado del viaje recreado. | "RECREATED_TRIP" |
father_trip_id | string | ID único del viaje original (viaje padre). | "64729e1f8c9b652308de2348" |
son_trip_id | string | ID único del nuevo viaje recreado (viaje hijo). | "64729c1f8c9b652308de2348" |
Importante
Es muy aconsejable que tu servidor pueda manejar esta eventualidad
Tip
A partir de un viaje recreado recibirás notificaciones por webhook de cambios de estatus del mismo
Respuesta Esperada
Desde el lado de Ridery se espera una respuesta de tipo 200 hacia donde envíe el Webhook.
Importante
No hay reintento de Webhook si no se obtiene un 200 de parte de tu servidor.
Desactivación del Webhook
De ser necesario, también se puede desactivar el webhook configurado accediendo al módulo de credenciales.
Credenciales
Se puede configurar el envío de un token de autenticación por cabecera de parte de Ridery de ser necesario.