Occasional missions¶
An order holds shared client, contact, message and category information. It contains an outbound journey and an optional return, each with its own schedule and assignments. Addresses, vehicle and driver are optional. These routes require the network's Occasional missions option; operators and regulators can write, readers can read. Authorized team scope applies to orders and journeys.
Operations¶
Times and validation¶
Timestamps carry an explicit UTC offset. List dates (start_date, end_date, inclusive) and departure-day validation use the network timezone. A new departure date cannot be in the past. Arrival must follow departure and fall no later than the next local day. The return cannot start before outbound arrival.
The return proposal reverses addresses, keeps assignments and adds three elapsed hours to outbound arrival. Its duration matches the outbound journey. Calculations use UTC instants, including daylight-saving transitions; display uses the network timezone.
Business rejections return 422 with detail.code, detail.message and, when known, detail.field (a payload field path). Structural validation returns Pydantic detail[] with loc. Required messages include “Donnez un nom à la mission.”, “Indiquez qui commande le transport.” and “L'arrivée doit tomber au plus le lendemain du départ.”. Passenger count is an integer greater than or equal to zero.
Editing, cancellation and duplication¶
After actual departure, only shared contact, phone, message and category fields remain editable through these management routes. Cancellation is permanent and unavailable from scheduled departure onwards. A cancelled return remains in history; a new return receives a new identity. PUT does not create or reactivate a journey.
Duplication keeps only journeys that have not been cancelled, with fresh identities and no inherited execution facts, assignments or tracking link. If the outbound journey is cancelled, the remaining return becomes the copy's outbound journey. planned_departure_at sets the new first departure. Optional overrides save the fully edited form in one request; its first departure must match that timestamp. Explicitly entered assignments and an explicitly requested fresh link draft are new creations. When all journeys are cancelled, a date alone is insufficient: a fully re-entered form is required.
Categories, clients and conflicts¶
The six initial categories are Scolaire, Mariage, Entreprise, Événementiel, Sport and Tourisme. They are created on the network's first access to its categories, each with its own color: blue, yellow, orange, purple, green and teal, in that order. These colors can be changed. A network whose categories already exist is left unchanged, and a deleted initial category is not recreated. A used category is archived to preserve history; an unused category is permanently deleted.
Client search ignores case, accents and punctuation. Conflicts use strict overlap of planned times: journeys touching at a boundary do not overlap. Cancelled missions are excluded. Responses include the conflicting mission's name and times. A vehicle without associated equipment exposes vehicle_without_license=true.
Tracking updates¶
From the beginning of approach until tracking ends, a change or cancellation publishes a WebSocket message occasional_mission_updated or occasional_mission_cancelled with mission_id and occurred_at. The consumer reads the data again after reception. Execution and tracking-link operations are separate slices; a link draft created by management remains inactive.
Concurrent changes¶
A concurrent change can return 422 and ask the caller to reload the order. Management writes for an order are atomic: a rejected change does not leave a partially edited mission or category reference. A team transfer includes omitted and cancelled journeys. Changing shared contact information notifies every journey whose tracking is in progress. Updating a deleted category returns 404, including when deletion finishes while the update is being prepared; an update never recreates the category.
Planned route and approach¶
Creating a mission or changing its addresses calculates the departure-to-arrival route on the server. Geometry uses precision-6 polyline encoding, distance is in meters and duration in seconds. An entered distance remains authoritative and is never replaced by recalculation. Without both addresses, no routing request is made. Routing failure preserves the save with no route or calculated distance; the next save retries.
GET /api/v4/groups/<group_id>/occasional/missions/<mission_id>/route returns the stored route or 404 no_route. POST on the same URL requests recalculation before actual departure; an unavailable routing service returns 503 routing_unavailable, without reverting other stored data.
Driver V6 requests a separate approach route through POST /nav-data-processor-api/v5/groups/<group_id>/devices/<device_id>/occasional-missions/<mission_id>/approach-route, with latitude and longitude. The device must match the session and have the assigned driver on duty, with the vehicle chosen at duty check-in. Started or cancelled missions return 409; missing departure coordinates return 422 missing_coordinates; no possible route returns 422 no_route; unavailable routing returns 503 routing_unavailable. This calculation never changes mission data.
Driver V6 execution¶
The Driver list GET /nav-data-processor-api/v5/groups/<group_id>/devices/<device_id>/occasional-missions?service_date=2026-10-06 returns missions assigned to the tablet's driver. Its service day runs from local 04:00 to the next local 04:00 in the group timezone, including daylight-saving changes. Detail responses retain customer, contact and category context.
Commands POST .../<mission_id>/approach, /start, /count, /pause and /end accept a stable event_id and optional occurred_at (receipt time by default). Driver keeps the original timestamp and identity in its persistent queue without expiry. /count carries total_on_board, /pause carries paused, and /end carries ended_by (manual or auto). Mutation responses contain the mission without order context: merge execution fields into the cache or reload its detail.
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"}'
The session must belong to the device. The duty and assignment at event time authorize offline events; replay duty check-ins before missions. The Mongo journal preserves idempotency beyond the HTTP cache's 24 hours. Reusing an identity for another fact is rejected. Out-of-order counts and pauses follow original timestamps. An end received before its start is retained for replay; planned times never end a mission implicitly.
The duty vehicle remains separate from the planned vehicle. Differences are recorded; the vehicle cannot change after actual departure. Authenticated relief through a duty check-in on the same tablet preserves the mission and records the new driver. Replaying an older duty does not replace the current duty's mission. Starting releases the regular trip and attributes positions to occasional_mission_id, even without GTFS. Actual distance uses GPS from 80% of planned distance, otherwise planned distance; all dates are summed and completed detail refreshes when positions arrive later.
GET /api/v4/groups/<group_id>/occasional/missions/<mission_id>/history exposes events and assignments, including rejected starts of cancelled missions. order_events adds the actions taken on the order, shared by the outbound and return journeys: order_created, link_created, link_activated, link_deactivated, link_code_regenerated, link_protection_enabled and link_protection_removed. Each carries user_id and user_email (the account's address at the time of the action, as in the audit log); both are null on orders created before they were recorded. The order also exposes its author in created_by. Driver messaging accepts kind: "occasional_mission_not_found"; omitting kind retains existing behavior.
Before check-in, the list accepts driver_id with X-Driver-Code, validated like duty check-in. Without these parameters it uses the current duty driver. Cancelled missions remain visible. The active tablet mission stays in the list after driver relief, even outside its planned service day. Late position kilometres and the completed mission distance commit atomically.
The Driver day response includes timezone, the network’s IANA timezone, for local display and the 04:00 service-day cache boundary. Cancelled assigned missions remain visible. After an authenticated relief on the same tablet, its active mission remains in the new driver’s list.
GET /api/v4/groups/<group_id>/occasional/missions/<mission_id>/history also returns positions, with coordinates, original GPS times and reception times. Late samples are matched to the historical duty and assignment at GPS time. Before departure they require an explicit approach event with the same device, duty, driver and vehicle. Each selection or resumption emits a new event: the latest at GPS time selects the mission; a tie between missions is rejected. An active commercial mission remains authoritative. A start closes earlier approach focuses; after completion, a new approach selection is required. The first approach time is preserved. Approach kilometres and edges crossing actual departure never contribute to commercial distance. They never move a tablet now working another service. Device and GPS timestamp form a durable replay identity without TTL. Distances are adjusted between chronological neighbours using the existing GPS guards; client deltas do not identify their predecessor and cannot describe out-of-order insertions reliably. A sample without historical proof is not assigned to today’s active mission.
Driver’s existing relief flow remains online and must acknowledge queued mission actions before changing drivers. The start and end no longer need to be acknowledged before the GPS backlog: when they arrive, the samples already received are re-attributed to the real departure and end, the mission distance is recomputed, and samples after the end return to the vehicle's regular kilometres. The approach event must still reach the API before the approach samples. Known facts replay independently of the duty lookup; new late facts require the historical duty and assignment to remain available. No additional maximum replay age applies.
The private history.current_message_recipient field is {device_id, duty_id, driver_id} (three strings) or null. It identifies only the driver currently on duty: a mission that has neither ended nor been cancelled, exactly one non-archived device carrying the mission, exactly one open duty already started on that device, a duty ID matching the current device pointer, and an identified driver matching the device driver. Any ambiguity returns null. The planned driver and historical drivers are never fallbacks; a valid relief returns the new driver. Public tracking does not contain this field.
Op refreshes this history before opening the message form and before sending. It disables the button without a certain recipient and closes the form if the device/duty/driver identity changes or refresh fails. This read describes current state; it does not reserve the duty. Existing messaging retains a residual network delay between verification and sending, without atomicity guarantees with a driver relief.
Devices on a mission¶
GET /api/v2/groups/<group_id>/devices and GET /api/v2/groups/<group_id>/devices/<device_id> expose two mission ids, for a network with the occasional missions feature and flag (absent otherwise):
approaching_occasional_mission: the mission whose approach the device declared. It is cleared at the start, when the mission is cancelled, when it is planned for another driver, and on any duty change on the device. It changes neitherdrive_modenor the kilometres.current_occasional_mission: the mission under way, from start to end, withdrive_modeset tooccasional.
Each set or clear reaches the device event stream under the same field name: occasional_mission_approach (id or null), occasional_mission_start, occasional_mission_end, and duty_check_in / duty_check_out when they end an approach.
Tracking link and public page¶
GET /orders/<order_id>/link returns the URL, activation and code-protection state. POST creates a draft; /activate keeps its URL, /regenerate replaces the code (or removes protection), and /deactivate invalidates the old URL and creates a new draft. Only creation and regeneration return the plaintext code, once. GET /link/preview uses the reader’s Op permissions and team scope, without a code prompt or a public opening. The order list and detail summarise the current link in link: {"active": …, "protected": …}, or null when no link was created. This summary carries neither the URL nor the code.
The page uses GET /api/v4/occasional-tracking/<token>. Unknown tokens and ineligible groups return 404. The draft, invalid and code_required states contain no journey data: only group_name and nullable group_logo_url, so passengers know which network sent the link, including when it is deactivated or expired. Open states schedule, live, arrived contain the programme and available information. POST /code accepts six digits and returns a grant lasting at most fifteen days, subsequently sent only in Authorization. Code replacement, deactivation or expiry invalidates it. Five failures from one IP block entry for fifteen minutes; fifty across the link block it for one hour. HTTP 429 includes detail.retry_at.
Live tracking opens one hour before departure and follows actual arrival; a running journey takes priority over another open window. Expiry is recomputed from non-cancelled journeys: last reference arrival + 2 hours, or planned arrival + 4 hours for a started but unfinished journey. This public limit takes priority even over a very late departure; it never closes operational tracking in Op. A position at least ten minutes old remains available with its timestamp and stale=true, without an ETA.
record_opening=true is reserved for the first successful page load; polls keep the default false. Known robots and Op previews are not counted. The journal stores neither IP addresses nor visitor identifiers. The page’s privacy assessment remains pending before activation.