Skip to main content

Trip Export (Send Trip)

Trip export pushes planned trips out of SWAT into the dispatch system a project is connected to — a transport management system, a driver app backend, or a third-party logistics platform. It is the last step of the planning workflow: once routes are optimized and violations resolved, each vehicle's plan is sent as one trip.

The push is one-way and point-in-time. Anything changed afterwards — reassigning an order, reordering stops, editing a time window — does not reach the dispatch system until the trip is sent again.

Triggering an Export​

Trip export runs as a bulk task:

POST /api/v2/microservices/bulk/task
{
  "project_id": 111,
  "type": "<trip export task type for your connector>",
  "payload": {
    "vehicles_ids": [418922, 418923],
    "return_full_objects": false
  },
  "execution_mode": "async"
}
FieldNotes
typeOne task type is registered per dispatch connector; the value for your project is issued with the integration.
payload.vehicles_idsAt least one vehicle ID, unique. One trip is sent per vehicle.
payload.return_full_objectsWhen set, the result carries the export attempt records and exported vehicle objects in full rather than their IDs alone.
execution_modeasync is the normal choice — a batch of trips involves one outbound call per vehicle.

See Start bulk operation for the full request and response schemas.

How a Trip Is Assembled​

One trip is built per vehicle, from that vehicle's assigned stops — stops that are assigned, in service, or already completed, and that carry both an operations location and an order.

  • Pickups define the trip, not its stops. The pickup location becomes the trip's origin, and the pickup times its on-dock and release window. Delivery stops are what the stop list contains.
  • Consecutive stops at the same location are one stop. Grouping is by consecutive location, not by distinct location — a route that returns to somewhere it has already been reports two stops in visiting order rather than one merged stop.
  • Orders belong to the stop, not the trip. Every booking delivered at a location becomes an order under that stop, numbered from 1 within the stop.
  • Stop timing spans the whole visit. Arrival is the earliest scheduled time across the stop's nodes, departure the latest plus its service time, so a location serving several bookings reports the entire time the vehicle stands there.
  • A vehicle whose route yields no valid stop is rejected rather than sent as an empty trip. The rejection is recorded as a failed attempt against that vehicle.

Example Payload​

The exact field names and envelope are defined by the dispatch connector — each integration has its own contract. The example below is representative of the shape SWAT produces: a header, trip-level fields, and stops that carry their own orders.

{
  "messageHeader": {
    "messageId": "<hash of this payload, used for de-duplication>",
    "orgCode": "<per-project configuration>",
    "companyCode": "<per-project configuration>",
    "timestamp": "2026-09-14T02:11:07Z"
  },
  "plannedDispatchDate": "2026-09-14T06:00:00Z",
  "loadId": "418922",
  "originSiteNumber": "<pickup location external id>",
  "plannedVehicleType": "10T Chiller",
  "vehicleName": "<vehicle service number>",
  "driverId": "<driver external id>",
  "plannedOnDockDateTime": "2026-09-14T06:00:00Z",
  "plannedReleaseDateTime": "2026-09-14T06:45:00Z",
  "intermediateStops": [
    {
      "stopSequence": 1,
      "stopType": "Delivery",
      "destinationSiteNumber": "<location external id>",
      "destinationSiteName": "Central Store 21",
      "destinationAddress": "88 Sukhumvit Road",
      "destinationZipCode": "10110",
      "destinationCountry": "TH",
      "latitude": "13.736717",
      "longitude": "100.523186",
      "scheduledArrivalDateTime": "2026-09-14T08:12:00Z",
      "scheduledDepartureDateTime": "2026-09-14T08:34:00Z",
      "windowStartDateTime": "2026-09-14T08:00:00Z",
      "windowEndDateTime": "2026-09-14T10:00:00Z",
      "orderType1": "TC",
      "Orders": [
        {
          "OrderSequence": 1,
          "OrderNumber": "<order external id>",
          "DeliveryNumber": "<order external id>",
          "ForExternalPlannerId": "<order uid as supplied to SWAT>"
        }
      ]
    }
  ]
}

Points worth knowing when mapping your own connector onto this:

  • Trip identity is the vehicle. The trip identifier is the vehicle ID, which identifies exactly one planned trip because a vehicle belongs to a single simulation. Re-exporting the same vehicle re-submits the same identifier.
  • De-duplication is content-based. The message id is a hash over the payload itself. A trip re-sent without changes hashes identically, which a receiving system may read as a duplicate rather than as an update.
  • Optional fields are sent as explicit null, not omitted, where the connector's contract expects the full shape.
  • Fields SWAT does not model are always empty — trailer, fleet code, stop-level contact person and phone, seal number, and free-text instructions among them. If your dispatch system requires one of these, it has to come from its own master data.
  • Codes that are not modelled in SWAT come from project configuration — organisation and company codes, and the map from an order's product kind onto the connector's order type codes, with a configured default. An unmapped kind with no default is reported rather than guessed, because a wrong code is worse than a visible rejection.

Tracking the Result​

The task records one export attempt per vehicle it tried to send, whether it succeeded or failed, keeping the payload that was sent and the dispatch system's reply. The task result carries the attempt IDs and the IDs of the vehicles that were accepted.

A vehicle counts as exported only when the dispatch system itself accepts the trip — not merely when the request is delivered. A receiving system that answers 200 while reporting a processing failure in its body is treated as a rejection.

Each vehicle also carries the outcome of its most recent attempt:

StatusMeaning
Not sentNo export has been attempted.
SendingAn export is in progress.
SentThe dispatch system accepted the trip.
FailedThe trip was rejected before or by the dispatch system.

Alongside the status, a vehicle records the timestamp of the last attempt and the user who initiated it. Orders carry their own export status as well, so a booking can be traced to whether the trip carrying it arrived.

When an Export Fails​

CauseWhat to do
Nothing to send — the route yields no valid stop, because nothing is assigned or its stops lack a locationFix the plan, then send again.
Credentials or connector configuration missing or rejectedEvery trip in the batch fails identically, with the reason on each attempt. Fix the project configuration, then send again.
The dispatch system refused the trip — data it requires is missing or does not match its master dataRead the reason recorded on the attempt; it names what the receiving system objected to.