Flota¶
Los medios empleados para prestar el servicio: quién conduce, con qué vehículo, equipado con qué dispositivo y desde qué cochera.
drivers¶
Conductor — la persona que realiza las expediciones. El conductor no es un usuario de la interfaz de explotación: se identifica en la aplicación Pysae Driver, en el momento de su toma de servicio.
Identificador <driver_id>. Un conductor tiene un número de empleado, pertenece a uno o varios equipos y puede archivarse cuando deja la red: el archivado lo retira de la explotación diaria sin borrar el historial al que está vinculado.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/drivers |
Lista los conductores del grupo |
GET /api/v4/groups/<group_id>/drivers/<driver_id> |
Describe un conductor |
GET /api/v4/groups/<group_id>/export/drivers |
Exporta los conductores en formato CSV |
vehicles¶
Vehículo — el autobús urbano o interurbano que presta servicio en la red. Lleva su número de flota, su matrícula, su tipo y su energía, su capacidad y los equipos embarcados que lo acompañan.
Identificador <vehicle_id>. Un vehículo pertenece a uno o varios equipos y tiene un estado de explotación, que distingue un vehículo en servicio de un vehículo inmovilizado.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/vehicles |
Lista los vehículos del grupo |
GET /api/v4/groups/<group_id>/vehicles/<vehicle_id> |
Describe un vehículo |
GET /api/v4/groups/<group_id>/vehicles/public |
Proporciona los datos que pueden difundirse a los viajeros |
GET /api/v4/groups/<group_id>/export/vehicles |
Exporta los vehículos en formato CSV |
devices¶
Dispositivo — el teléfono o la tableta del conductor, en el que se ejecuta la aplicación Pysae Driver. Es el que transmite la posición del vehículo y el avance de la expedición y, por tanto, la fuente de todo el tiempo real: sin un dispositivo en servicio, una expedición no se sigue.
Identificador <device_id>. Un dispositivo está vinculado al vehículo a bordo del cual circula y conoce la expedición que realiza en un momento dado, designada por el triplete identificador de expedición, fecha de servicio y gtfs_id. También tiene sus propios metadatos: modelo, sistema operativo, versión instalada de la aplicación.
Un dispositivo se considera conectado mientras haya intercambiado datos con la API en un plazo inferior al configurado en el grupo (dos minutos por defecto, ajustable y distinto según el tipo de equipo). Este intercambio puede ser una posición, pero también un cambio de expedición, un recuento de viajeros o una toma de servicio: un dispositivo que pierde la señal GPS pero sigue comunicándose permanece conectado. La fecha del último intercambio figura en connected_at, que no debe confundirse con ts, que fecha la última posición conocida. La lista de dispositivos conectados (devices/online) devuelve este ts, así como off_itinerary, que indica si el dispositivo está fuera del recorrido previsto; un campo sin valor no aparece en la respuesta.
Para las posiciones procedentes de un dispositivo telemático, source_equipment_provider identifica al proveedor cuando se conoce (capte para Capte). Este campo opcional también está presente en el estado en línea. Un valor ausente o nulo no permite deducir el proveedor a partir del número de serie. Los dispositivos Capte existentes se completan al recibir una nueva trama; no se requiere ninguna migración.
Un dispositivo Capte lleva también current_headsign, el letrero que muestra su dispositivo telemático: número público de la línea (route_short_name), variante de una línea escolar (route_variant), texto (label) y código (code), tal como los envía el dispositivo telemático, salvo cuando la tabla de códigos de letrero del grupo declara ese código: route_short_name toma entonces la línea de la tabla, sea cual sea la línea enviada (algunos dispositivos telemáticos envían el código en su lugar, «3514» para la 5R de la línea 3500), y route_variant la variante de la tabla cuando la línea enviada no tiene ninguna. Una variante enviada por el dispositivo telemático sigue teniendo prioridad, el código sigue siendo el que envía el dispositivo telemático, y un código ausente de la tabla, como el código de servicio 1000, deja el letrero tal cual. El campo solo se actualiza cuando cambia lo que muestra: una trama que no menciona el letrero lo deja como está, y un letrero borrado por el dispositivo telemático solo conserva changed_at. Una modificación de la tabla que cambia la línea o la variante de un código se aplica a la siguiente trama del dispositivo telemático, aunque su letrero no haya cambiado. changed_at, en segundos Unix, fecha la trama que cambió el campo; para un dispositivo telemático cuyo letrero se conocía antes de la aparición del campo, es la primera trama recibida después. Solo se alimenta para un grupo que dispone de la asignación automática de expediciones de los dispositivos telemáticos (feature telematic_trip_assignment), y solo se devuelve en la lista y el detalle de los dispositivos leídos con un rol en el grupo: no aparece en la lectura pública sin rol ni en devices/online, como en el caso de un dispositivo Pysae Driver. Sus cambios llegan también al historial de eventos, mediante un evento vehicle_data.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/devices |
Lista los dispositivos del grupo |
GET /api/v4/groups/<group_id>/devices/<device_id> |
Describe un dispositivo y su estado actual |
GET /api/v4/groups/<group_id>/devices/online |
Lista los dispositivos conectados actualmente |
Los datos de campo llegan por las rutas /nav-data-processor-api/, servidas por un despliegue dedicado al tráfico de la aplicación del conductor.
depot¶
Cochera — el lugar de estacionamiento del que salen y al que vuelven los vehículos. Sirve de referencia a la explotación: a partir de ella se contabilizan los trayectos en vacío entre la cochera y el inicio de la expedición.
Identificador <depot_id>.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/depots |
Lista las cocheras del grupo |
duties¶
Servicio de conducción — el periodo durante el cual un conductor presta servicio, desde su toma de servicio hasta su fin de servicio. Es el objeto que vincula efectivamente un conductor, un vehículo, un dispositivo y las expediciones realizadas.
Identificador <duty_id>. Un servicio lleva obligatoriamente el dispositivo utilizado y hace referencia al conductor y al vehículo empleados. Contiene la lista de expediciones realizadas, los kilómetros en vacío recorridos y la información de toma y fin de servicio, incluidas, en su caso, las respuestas al cuestionario de control.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/duties |
Lista los servicios de un periodo |
GET /api/v4/groups/<group_id>/duties/<duty_id> |
Describe un servicio y sus expediciones |
Allí donde la planificación prevé, el servicio de conducción constata.
duty-checklist¶
Cuestionario de servicio — la lista de controles que el conductor completa en la toma o el fin de su servicio: estado del vehículo, limpieza, anomalías detectadas. Su composición se configura por grupo, y las respuestas se conservan en el servicio de conducción correspondiente.
Sin identificador propio: el cuestionario es una configuración del grupo.
Esta configuración se gestiona desde las aplicaciones Pysae y no se publica en la especificación pública.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/config/duty-checklist |
Proporciona el cuestionario configurado |
PUT /api/v4/groups/<group_id>/config/duty-checklist |
Modifica el cuestionario |