Misiones ocasionales¶
Un pedido agrupa la información del cliente, el contacto, el mensaje y la categoría. Contiene una ida y, opcionalmente, una vuelta, cada una con sus horarios y sus asignaciones. Las direcciones, el vehículo y el conductor son opcionales. Estas rutas requieren la opción Misiones ocasionales de la red; los operadores y reguladores pueden escribir, los lectores pueden consultar. El perímetro de los equipos autorizados se aplica a los pedidos y a los trayectos.
Operaciones¶
Horarios y validación¶
Las horas llevan un desfase UTC explícito. Las fechas de las listas (start_date, end_date, incluidas) y la validación del día de salida utilizan la zona horaria de la red. Una nueva fecha de salida no puede estar en el pasado. La llegada debe ser posterior a la salida y producirse como muy tarde al día siguiente en esa zona horaria. La vuelta no puede comenzar antes de la llegada de la ida.
La propuesta de vuelta invierte las direcciones, retoma las asignaciones y añade tres horas transcurridas a la llegada de la ida. Su duración es la de la ida. Los cálculos utilizan instantes UTC, incluso durante los cambios de hora; la visualización utiliza la zona horaria de la red.
Un rechazo de negocio responde 422 con detail.code, detail.message y, cuando se conoce, detail.field (ruta del campo en el payload). Las validaciones de estructura responden con la lista Pydantic detail[] y sus loc. Los mensajes obligatorios incluyen «Donnez un nom à la mission.», «Indiquez qui commande le transport.» y «L'arrivée doit tomber au plus le lendemain du départ.». El número de pasajeros es un entero mayor o igual que cero.
Edición, cancelación y duplicación¶
Tras la salida real, en estas rutas de gestión solo siguen siendo modificables los campos compartidos de contacto, teléfono, mensaje y categoría. Una cancelación es definitiva e imposible a partir de la salida prevista. Una vuelta cancelada permanece en el historial; una nueva vuelta recibe una nueva identidad. El PUT no crea ni reactiva ningún trayecto.
La duplicación conserva únicamente los trayectos no cancelados, con nuevas identidades y sin retomar los hechos de ejecución, las asignaciones ni el enlace de seguimiento. Si la ida está cancelada, la vuelta restante pasa a ser la ida de la copia. planned_departure_at fija la nueva primera salida. Los overrides opcionales permiten guardar el formulario completamente modificado en una sola petición; la primera salida debe corresponder a esa fecha. Las asignaciones introducidas expresamente y el nuevo borrador de enlace solicitado expresamente son creaciones nuevas. Cuando todos los trayectos están cancelados, una fecha sola no basta: es necesario un formulario introducido de nuevo por completo.
Categorías, clientes y conflictos¶
Las seis categorías iniciales son Scolaire, Mariage, Entreprise, Événementiel, Sport y Tourisme. Se crean en el primer acceso a las categorías de la red, cada una con un color: blue, yellow, orange, purple, green y teal, en ese orden. Estos colores siguen siendo modificables. Una red cuyas categorías ya existen no se modifica, y una categoría inicial eliminada no se vuelve a crear. Una categoría utilizada se archiva para preservar el historial; una categoría sin uso se elimina definitivamente.
La búsqueda de clientes ignora mayúsculas, acentos y puntuación. Los conflictos utilizan un solapamiento estricto de los horarios previstos: dos trayectos que se tocan exactamente no se solapan. Las misiones canceladas quedan excluidas. La respuesta indica el nombre y los horarios de la misión afectada. Un vehículo sin equipo asociado expone vehicle_without_license=true.
Actualización del seguimiento¶
Desde el inicio de la aproximación y hasta el final del seguimiento, una modificación o una cancelación publica un mensaje WebSocket occasional_mission_updated u occasional_mission_cancelled con mission_id y occurred_at. El consumidor vuelve a leer los datos tras la recepción. La ejecución y las operaciones del enlace de seguimiento son entregas distintas; un borrador de enlace creado por la gestión permanece inactivo.
Modificaciones concurrentes¶
Una modificación concurrente puede responder 422 y pedir que se recargue el pedido. Las escrituras de gestión de un pedido son atómicas: una misión o una referencia de categoría no queda parcialmente modificada tras un rechazo. El cambio de equipo abarca también los trayectos omitidos y cancelados. Tras una modificación del contacto compartido, cada trayecto en seguimiento recibe una notificación. Un PUT de una categoría eliminada responde 404, incluso si la eliminación termina durante la preparación de la modificación; el PUT nunca vuelve a crear la categoría.
Recorrido previsto y aproximación¶
La creación y la modificación de las direcciones calculan el recorrido salida–llegada en el servidor. El trazado utiliza una polyline de precisión 6, una distancia en metros y una duración en segundos. Una distancia entered sigue teniendo prioridad; el recálculo no la sustituye. Sin dos direcciones, no se realiza ninguna llamada al motor. Una avería del motor conserva el registro sin trazado ni distancia calculada; el siguiente registro lo vuelve a intentar.
GET /api/v4/groups/<group_id>/occasional/missions/<mission_id>/route devuelve el trazado registrado, o 404 no_route. POST sobre la misma URL solicita un recálculo antes de la salida real; en caso de indisponibilidad, responde 503 routing_unavailable, sin anular los demás datos registrados.
Driver V6 solicita un trazado de aproximación distinto mediante POST /nav-data-processor-api/v5/groups/<group_id>/devices/<device_id>/occasional-missions/<mission_id>/approach-route, con latitude y longitude. El dispositivo debe ser el de la sesión y llevar al conductor asignado en servicio, así como un vehículo de servicio; este autocar puede diferir del vehículo previsto. Una misión iniciada o cancelada responde 409; sin salida geolocalizada, 422 missing_coordinates; sin ruta posible, 422 no_route; con el motor no disponible, 503 routing_unavailable. Este cálculo no modifica ningún dato de la misión.
Ejecución en Driver V6¶
La lista de Driver GET /nav-data-processor-api/v5/groups/<group_id>/devices/<device_id>/occasional-missions?service_date=2026-10-06 devuelve únicamente las misiones asignadas al conductor de la tableta. La jornada va de las 4 h locales a las 4 h del día siguiente en la zona horaria de la red, incluso en los cambios de hora. El detalle conserva el contexto de cliente, contacto y categoría. La respuesta de la lista expone timezone (identificador IANA de la red) para la caché y la visualización locales.
Los comandos POST .../<mission_id>/approach, /start, /count, /pause y /end aceptan un event_id estable y un occurred_at opcional (la recepción por defecto). Driver conserva la marca de tiempo original y la identidad en su cola persistente sin caducidad. /count lleva total_on_board, /pause lleva paused, /end lleva ended_by (manual o auto). Las mutaciones devuelven la misión sin el contexto del pedido: fusione los campos de ejecución en la caché o vuelva a cargar el detalle.
curl --request POST "$API/nav-data-processor-api/v5/groups/$GROUP/devices/$DEVICE/occasional-missions/$MISSION/start" \
--header "Authorization: Bearer $TOKEN" --header 'Content-Type: application/json' \
--header 'x-pysae-api-request-id: stable-request-id' \
--data '{"event_id":"stable-event-id","occurred_at":"2026-10-06T08:00:00Z"}'
La sesión debe pertenecer al dispositivo. El servicio y la asignación en el instante del hecho autorizan los eventos sin conexión; reproduzca las tomas de servicio antes que las misiones. El registro de Mongo garantiza la idempotencia más allá de las 24 h de la caché HTTP. Reutilizar una identidad para otro hecho se rechaza. Los recuentos y pausas que llegan desordenados siguen el instante de origen. Un final recibido antes de la salida se conserva para la reproducción; ningún final se deduce del horario previsto.
El autocar del servicio sigue siendo distinto del autocar previsto. La diferencia se registra en el historial; el autocar ya no puede cambiar tras la salida real. El relevo autenticado mediante la toma de servicio en la misma tableta conserva la misión y registra el nuevo conductor. La reproducción de un servicio antiguo no sustituye la misión del servicio actual. La salida libera la expedición regular y vincula las posiciones a occasional_mission_id, incluso sin GTFS. La distancia realizada es la del GPS a partir del 80 % de la distancia prevista; en caso contrario, la prevista; todas las fechas se suman y la distancia finalizada se actualiza de forma atómica con los kilómetros si llegan posiciones después.
GET /api/v4/groups/<group_id>/occasional/missions/<mission_id>/history expone los hechos, las asignaciones y positions (coordenadas y horas GPS/de recepción), incluida una salida rechazada en una misión cancelada. order_events añade las acciones realizadas sobre el pedido, comunes a la ida y a la vuelta: order_created, link_created, link_activated, link_deactivated, link_code_regenerated, link_protection_enabled y link_protection_removed. Cada una lleva user_id y user_email (la dirección de la cuenta en el momento de la acción, como en el registro de auditoría); estos dos campos son nulos para un pedido creado antes de que se registraran. El pedido expone también su autor en created_by. La mensajería del conductor acepta kind: "occasional_mission_not_found"; omitir kind mantiene el comportamiento existente.
Antes de la toma de servicio, la lista acepta driver_id y el código en la cabecera X-Driver-Code, validados como en el check-in. Sin estos parámetros, utiliza el conductor del servicio actual. Las misiones canceladas siguen visibles. La misión activa permanece en la lista tras un relevo, incluso fuera de la jornada planificada.
Las posiciones retrasadas se atribuyen al servicio y a la asignación históricos según su hora GPS. Antes de la salida, exigen un hecho de aproximación explícito con el mismo dispositivo, servicio, conductor y vehículo. Cada selección o reanudación emite un nuevo hecho: el más reciente según la hora GPS elige la misión; un empate entre misiones se rechaza. La misión comercial activa sigue teniendo prioridad. Una salida cierra los focos de aproximación anteriores; tras el final, es necesaria una nueva selección de aproximación. El primer horario de aproximación no cambia. Ningún kilómetro de aproximación ni segmento que cruce la salida real contribuye a la distancia comercial. Siguen siendo legibles en history.positions tras el final; su recepción no desplaza una tableta que ahora está en otro servicio. El registro elimina duplicados por dispositivo y hora GPS, sin TTL. Los kilómetros se recalculan entre posiciones cronológicamente vecinas, con las protecciones GPS existentes; el delta del cliente no identifica a su predecesor y, por tanto, no se utiliza para estas inserciones fuera de orden. Una posición sin prueba histórica no se vincula a la misión mostrada actualmente.
El relevo existente se hace en línea: Driver confirma su cola de hechos de misión antes de cambiar de conductor. La salida y el final ya no tienen que confirmarse antes del backlog GPS: al recibirlos, las posiciones ya recibidas se reatribuyen a la salida y al final reales, la distancia de la misión se recalcula y las posiciones posteriores al final se incorporan al kilometraje regular del vehículo. El hecho de aproximación debe seguir llegando a la API antes que las posiciones de aproximación. Un hecho ya conocido puede reproducirse sin volver a leer el servicio; un nuevo hecho tardío exige que el servicio histórico y la asignación sigan disponibles. No se aplica ningún plazo máximo adicional.
El campo privado history.current_message_recipient vale {device_id, duty_id, driver_id} (tres cadenas) o null. Designa únicamente al conductor actualmente en servicio: misión no finalizada/no cancelada, un único dispositivo no archivado que lleva la misión, un único servicio abierto iniciado en ese dispositivo, identificador del servicio igual al puntero actual y conductor informado idéntico al del dispositivo. Cualquier ambigüedad devuelve null. El conductor planificado y los conductores anteriores nunca sirven de alternativa; un relevo válido da el nuevo conductor. El seguimiento público no contiene este campo.
Op actualiza este historial antes de abrir y antes de enviar el mensaje. Deja el botón no disponible si no hay un destinatario seguro y cierra la introducción si la identidad dispositivo/servicio/conductor cambia o si la actualización falla. Esta lectura describe un estado actual; no reserva el servicio. La mensajería existente conserva un retraso de red residual entre la verificación y el envío, sin garantía de atomicidad con un relevo.
Dispositivos en misión¶
GET /api/v2/groups/<group_id>/devices y GET /api/v2/groups/<group_id>/devices/<device_id> exponen dos identificadores de misión, para una red que tiene la feature y el flag de las misiones ocasionales (en caso contrario, ausentes):
approaching_occasional_mission: misión cuya aproximación ha declarado el dispositivo. Se retira en la salida, al cancelar la misión, cuando se replanifica para otro conductor y en cualquier cambio de servicio en el dispositivo. No cambia nidrive_modeni los kilómetros.current_occasional_mission: misión en curso, de la salida al final, condrive_modeaoccasional.
Cada asignación o retirada llega al flujo de eventos del dispositivo con el mismo nombre de campo: occasional_mission_approach (identificador o null), occasional_mission_start, occasional_mission_end, y duty_check_in / duty_check_out cuando ponen fin a una aproximación.
Enlace y página de seguimiento¶
El GET /orders/<order_id>/link devuelve la dirección, la activación y la presencia de un código. El POST crea un borrador; /activate conserva su dirección, /regenerate sustituye el código (o retira la protección), y /deactivate invalida la dirección anterior y crea un nuevo borrador. Solo la creación y la regeneración devuelven el código en claro, una sola vez. El GET /link/preview utiliza los permisos de Op y los equipos del lector, sin introducir el código y sin contabilizar una consulta. La lista y el detalle de los pedidos resumen el enlace actual en link: {"active": …, "protected": …}, o null si no se ha creado ningún enlace. Este resumen no contiene ni la dirección ni el código.
La página utiliza GET /api/v4/occasional-tracking/<token>. Un token desconocido o una red no habilitada responde 404. Los estados draft, invalid y code_required no llevan ningún dato del trayecto: solo group_name y group_logo_url (nullable), para que el viajero sepa qué red le envía el enlace, incluso cuando está desactivado o caducado. Los estados abiertos schedule, live, arrived contienen el programa y la información disponible. POST /code acepta los seis dígitos y devuelve un grant válido como máximo quince días, enviado después exclusivamente en Authorization. Se invalida al sustituir el código, al desactivarlo o al caducar. Cinco fallos desde una misma IP bloquean quince minutos; cincuenta sobre el enlace bloquean una hora. El 429 indica detail.retry_at.
El tiempo real se abre una hora antes de la salida y sigue el final real; un trayecto en curso prevalece sobre otra ventana abierta. La caducidad se recalcula sobre los trayectos no cancelados: última llegada + 2 h, o llegada prevista + 4 h para un trayecto iniciado sin final. Este límite público sigue teniendo prioridad incluso para una salida muy tardía; nunca cierra el seguimiento en Op. Una posición con una antigüedad de al menos diez minutos sigue pudiendo mostrarse con su marca de tiempo y stale=true, sin ETA.
record_opening=true está reservado a la primera carga correcta; los polls mantienen su valor por defecto false. Los robots conocidos y la vista previa de Op no se contabilizan. El registro no contiene ni IP ni identificador de visitante. El aviso RGPD de la página está pendiente de finalizar antes de la activación.