En este documento, se describe el servicio de viajes a pedido de Fleet Engine. Se supone que leíste ¿Qué es Fleet Engine? y que conoces la capacidad específica del servicio de Fleet Engine que necesitas.
Cuando leas esta documentación, ten en cuenta lo siguiente:
- Debes asignar viajes a los vehículos como una forma de modelar la asociación real entre el viaje y el conductor que lo completa. Lee Introducción a los vehículos para comprender mejor cómo funcionan en Flet Engine.
- En este documento, también se describen algunos elementos de los vehículos que se aplican solo a los viajes on demand.
- Flota Engine para viajes según demanda usa dos recursos:
TripyVehicle. Fleet Engine proporciona interfaces de REST y un servicio de gRPC:
¿Qué es un viaje a pedido?
En Fleet Engine, un viaje representa un viaje a pedido que puede lograr una variedad de objetivos de transporte. Por ejemplo:
- Personas: Transporta a una o más personas desde el punto de partida hasta el destino.
- Comida y bienes: Recoge uno o más pedidos de comida de una ubicación de la empresa determinada y entrega estos pedidos a uno o más destinatarios en sus ubicaciones.
Elementos del viaje
En la siguiente ilustración, se muestran los elementos básicos de un viaje: el ID del vehículo asignado, el estado del viaje y los puntos de referencia. Los tipos de puntos de referencia varían según la etapa del viaje: partida, intermedia y destino. En cualquier viaje, el uso de un punto de referencia o un destino intermedio es opcional. En el ejemplo de imagen, el vehículo llegó a la ubicación de retiro
Modelo de datos de los viajes
A medida que tu backend asigna viajes a vehículos, también debe conocer otros viajes programados para el vehículo. Por ese motivo, en los siguientes diagramas, se ilustra el modelo de datos del recurso Trip junto con el diagrama de su recurso Vehicle asociado. Puedes revisar ambos diagramas para explorar las relaciones entre los dos recursos y tener en cuenta lo siguiente:
- Los viajes se asignan a un vehículo por ID.
- La asociación de vehículos de viaje abarca varios a uno. Es decir, un viaje determinado puede ser el único programado para el vehículo o puede ser uno de muchos viajes para el vehículo.
- Los objetos de viaje contienen dos listas de puntos de referencia de viaje, una para el viaje en sí y otra para el vehículo asignado. Esto se explica con más detalle en este documento.
- El vehículo a pedido también tiene una lista de puntos de referencia de viaje, que se describe con más detalle en este documento.
Modelo de datos de viaje
Modelo de datos del vehículo
Tipos de viaje
Cuando tu servicio crea un viaje, puede establecer el campo tripType como cualquiera de las siguientes opciones: EXCLUSIVE o SHARED.
Viajes exclusivos
Un viaje exclusivo es aquel cuyo recorrido no se superpone con otros viajes, y uno que el vehículo completa antes o después de otros viajes de su horario. Esto significa que, cuando tu sistema asigna viajes exclusivos, solo puede asignarlos a un vehículo para que se complete en secuencia, no de forma simultánea. A modo de ejemplo, puedes crear viajes exclusivos con cualquiera de las siguientes características:
- Un viaje con un solo lugar de partida y un solo destino para un vehículo sin otros viajes en su horario
- Un viaje con punto de partida, punto de referencia intermedio y destino para un vehículo sin ningún otro viaje en su horario
- Un viaje en el que se agregan los puntos de partida y destino al final de un viaje ya programado para el vehículo. En estos casos, cada viaje es exclusivo para el otro, pero los viajes se ordenan de manera consecutiva. Además, esos viajes pueden incluir destinos intermedios si es necesario.
Viajes compartidos
Un viaje compartido es aquel cuyo recorrido puede superponerse con otras reservas de viajes. En el caso de estos tipos de viaje, tu sistema puede asignarlos para que ocurran simultáneamente con destinos intercalados. Por ejemplo, el descenso en un viaje puede ocurrir después del punto de partida para otro viaje. Además, es posible que los viajes compartidos no usen puntos de referencia intermedios.
Por lo general, usarías un viaje compartido para una de las situaciones de reducción compartida ilustradas en la sección Situaciones de viaje.
Puntos de referencia del viaje
Para Google Maps, un punto de referencia es un lugar en una ruta, generalmente definido por una coordenada de latitud y longitud. En el caso de los viajes a pedido, un punto de referencia se representa con un objeto TripWaypoint, que contiene información adicional, como la siguiente:
- El ID del viaje
- El
WaypointType, ya sea de recogida, intermedio o de destino - Información de la ruta y la distancia entre el punto de referencia del viaje anterior y el actual
- Condiciones de tráfico a lo largo de la ruta hacia el punto de referencia del viaje
- Tiempo de viaje y hora de llegada estimada al punto de referencia del viaje
Consulta las referencias:
Tipos de puntos de referencia del viaje
Un punto de referencia de viaje se define en relación con el ciclo de vida general de un viaje en vehículo:
- Punto de referencia de recogida: Se usa para el origen o el comienzo de un viaje, como cuando un conductor recoge un pedido de comida para su entrega posterior o cuando un conductor recoge a una persona para llevarla más tarde.
- Punto de referencia intermedio: Se trata de un destino intermedio que se puede utilizar para diversos fines, como cuando un conductor baja a un pasajero de la misma reserva, pero el viaje en sí no está completo, ya que quedan más pasajeros. Este punto de referencia es opcional y solo se puede usar para viajes exclusivos.
- Punto de referencia de destino: Se usa para la ubicación final del viaje, como cuando el pasajero restante sale del vehículo.
Lista de puntos de referencia de viajes
Una entidad Trip incluye dos listas de puntos de referencia, cada uno de los cuales es un campo repetido del tipo TripWaypoint. En una lista, se describen los campos necesarios para el viaje en sí y, en la otra, se describen todos los puntos de referencia restantes para el vehículo asociado con el viaje. Esto te permite tener un panorama completo de todos los elementos del viaje: el viaje y todo el recorrido del vehículo.
- Puntos de referencia restantes para el vehículo: Un campo llamado
vehicle_waypoints. Contiene todos los puntos de referencia restantes para todos los viajes asignados al vehículo. - Puntos de referencia restantes para el viaje: Un campo llamado
remaining_waypoints. Contiene puntos de referencia que el vehículo debe recorrer en secuencia antes del punto de llegada final del viaje. Consulta las situaciones en Situaciones de viaje.- En el caso de un viaje de un solo destino asignado a un vehículo sin otros viajes en su horario, esto incluiría solo una ubicación de partida y una de llegada, suponiendo que el vehículo no haya salido del punto de referencia.
- En cualquier otro caso de viaje en el que el vehículo también esté programado para otros viajes, los puntos de referencia restantes para cualquier viaje de su itinerario incluirían todos los puntos de referencia de otros viajes que el vehículo debe atravesar antes de llegar al punto de referencia para ese viaje. Por ejemplo, en un viaje de ida y vuelta en el que el vehículo está en la ruta de llegada para el viaje A, los puntos de referencia restantes para el viaje B incluirán el punto de referencia de llegada para el viaje A. Fleet Engine calcula esta información mediante el campo
vehicle_waypoints.
Consulta la referencia de la entidad Trip: gRPC o REST.
Situaciones de viajes
En los siguientes diagramas, se ilustra una variedad de situaciones de viajes admitidas. En estos casos, solo el viaje de reducción compartida es del tipo SHARED; todos los demás son EXCLUSIVE. En los diagramas también se muestra el estado del viaje y los puntos de referencia restantes para el vehículo que realiza el viaje, conceptos que se describen más adelante en esta guía.
Viaje de un solo destino
Un viaje de un solo destino corresponde a un viaje en EXCLUSIVE con una ubicación de partida y una de llegada. Por ejemplo, un conductor recoge a un pasajero de una ubicación y lo transporta a otro; o un conductor recupera un pedido de comida a domicilio de un restaurante y se lo deja a un cliente.
Viajes con varios destinos
Un viaje con varios destinos es un viaje en EXCLUSIVE que contiene uno o más destinos intermedios entre los puntos de partida y de llegada. Por ejemplo, tres clientes de transporte compartido reservan un viaje juntos desde el teléfono de una persona, pero cada uno tiene destinos independientes.
Viajes consecutivos
Los viajes consecutivos son viajes EXCLUSIVE que contienen una serie de viajes independientes que ocurren uno inmediatamente después del otro. Cada viaje de la cadena puede tener un destino único o varios. En esta situación, un conductor se compromete a recoger a otro cliente antes de completar el viaje actual.
Estos viajes solo se pueden asignar a vehículos que permitan la programación
de forma consecutiva. Consulta la referencia de Vehicle de REST y gRPC.
Viajes de agrupación compartidos
Un viaje de reducción compartida difiere de los otros tipos de viajes. En primer lugar, debe ser un viaje SHARED, no EXCLUSIVE.
Aquí, el vehículo ejecuta los viajes de forma simultánea en lugar de en secuencia, como sucede con los viajes exclusivos. Si bien un viaje de agrupación compartido comparte su recorrido con otros viajes, no comparte la información del lugar de recogida y llegada entre los viajes. En cambio, cada viaje es una reserva exclusiva de modo que el usuario final que reservó un viaje no puede ver la información de recogida o de destino de ningún otro viaje que no sea el suyo. Por ejemplo:
- Un servicio de transporte desde/hacia el aeropuerto recoge a varios clientes en su residencia y los deposita en diferentes terminales del aeropuerto a lo largo de la ruta. La persona 2 podría usar tu app para consumidores para hacer un seguimiento del progreso del viaje, pero su app solo muestra su parte del recorrido y no dónde se recogió a la persona 1 ni dónde se la bajará, aunque partes de sus recorridos se superpongan.
- Un repartidor de comida recoge tres pedidos del mismo restaurante para entregarlos en distintas residencias de los clientes. Con tu app para consumidores, la persona 3 puede ver dónde y cuándo se recogió su comida y la ruta del conductor, pero no puede ver las ubicaciones de entrega de alimentos para los usuarios 1 y 2.
Estado del viaje y su ciclo de vida
En esta sección, se describe el estado de los viajes y su impacto en el vehículo, así como diversas situaciones que puedes encontrar cuando asignas y administras viajes on demand.
Por lo general, un viaje avanza por varios estados, desde la creación hasta la finalización. En términos generales, un viaje puede estar activo o inactivo, según su estado. El estado del viaje afecta una variedad de situaciones de casos de uso con Fleet Engine, así como la capacidad de identificar el progreso del vehículo a lo largo del viaje. En el resto de este documento, se analizan esas situaciones.
En la siguiente tabla, se muestra el estado de los viajes según los tipos inactivos y activos.
| Estados activos de viajes | Estados de viajes inactivos |
|---|---|
NEW UNKNOWN_TRIP_STATUSENROUTE_TO_PICKUPARRIVED_AT_PICKUPENROUTE_TO_INTERMEDIATE_DESTINATIONARRIVED_AT_INTERMEDIATE_DESTINATIONENROUTE_TO_DROPOFF
|
COMPLETECANCELED
|
Estado del viaje y puntos de referencia restantes para vehículos
Cuando asignas viajes adicionales a un vehículo que ya está en ejecución, debes comprender la relación entre los puntos de referencia restantes del vehículo y cómo el estado del viaje afecta a esos puntos de referencia restantes.
Por ejemplo, puedes asignar una solicitud de transporte compartido nueva a un vehículo que solo admite viajes exclusivos y que está en medio de un viaje. En este caso, modelarías el viaje como un viaje de ida y vuelta. Al asignar un viaje de este tipo, el sistema debe asegurarse de que los puntos de referencia del viaje nuevo se produzcan después de los puntos de referencia del viaje en curso.
Durante el viaje en vehículo, Fleet Engine quita un punto de referencia de viaje anterior de la lista de puntos de referencia restantes solo cuando el vehículo informa que está en camino al siguiente destino o que se completó. Es decir, cualquiera de los siguientes:
- ENROUTE_TO_INTERMEDIATE_DESTINATION
- ENROUTE_TO_DROPOFF
- COMPLETED
Cuando el estado del viaje cambia a COMPLETED, Fleet Engine quita el punto de referencia final del viaje de la lista de puntos de referencia restantes del vehículo.
En cambio, los cambios de estado que indican la llegada a un punto de referencia no suelen tener ningún efecto en la lista de puntos de referencia restantes del vehículo:
- ARRIVED_AT_PICKUP
- ARRIVED_AT_INTERMEDIATE_DESTINATION
- ARRIVED_AT_DROPOFF
Para ilustrarlo con un ejemplo de un viaje a pedido, supongamos que el conductor recoge a un cliente de su residencia, lo transporta a un lugar donde espera a que el cliente complete una tarea y, luego, lo lleva de regreso a su residencia. Cuando se crea inicialmente, el viaje tiene tres puntos de referencia: PICKUP, INTERMEDIATE y DROPOFF. En la siguiente tabla, se muestran los resultados de una consulta de los puntos de referencia restantes en diferentes estados del recorrido:
| Estado del viaje | Puntos de referencia restantes |
|---|---|
ARRIVED_AT_PICKUP |
PICKUPINTERMEDIATEDROPOFF
|
ENROUTE_TO_INTERMEDIATE_DESTINATION |
PICKUPINTERMEDIATEDROPOFF
|
ARRIVED_AT_INTERMEDIATE_DESTINATION |
PICKUPINTERMEDIATEDROPOFF
|
ENROUTE_TO_DROPOFF |
PICKUPINTERMEDIATEDROPOFF
|
ARRIVED_AT_DROPOFF |
PICKUPINTERMEDIATEDROPOFF
|
COMPLETE |
PICKUPINTERMEDIATEDROPOFF |
Requisitos de estado para los viajes reasignados o cancelados
Antes de realizar cualquiera de las siguientes acciones, debes establecer el estado del viaje en NEW o CANCELED.
- Cuando se cambian las asignaciones de vehículos para un viaje. Por ejemplo, si un conductor rechaza la asignación de un vehículo para un viaje y esta debe reasignarse a otro vehículo.
- Cuando se borra la asignación de un vehículo para un viaje. Por ejemplo, si un conductor cancela un viaje en ruta y deseas borrar la asignación de vehículo, el estado debe ser
NEWoCANCELED.
Resultados de la búsqueda basados en el estado del viaje
Cuando usas el servicio SearchTrips para un vehículo específico, este muestra la lista de viajes activos en el SearchTripsResponse. Los viajes activos también aparecen en el campo active_trips de la entidad Vehicle. Consulta la referencia de SearchTripsResponse para obtener más detalles: gRPC o REST.
Por lo tanto, todos los viajes con estado activo aparecen en el campo active_trips, pero no los viajes completados o cancelados.