Tour

The tour consolidates all information needed to fulfill N shipments. In addition to the shipments, this includes information about the vehicle/trailer, driver, time span and execution date, stops, transport points (including tasks for the driver), as well as checklists and incidents for the entire tour.

Depending on whether sales orders in the customer system are referenced to a tour or not, fulfillment information for shipments can also be individually retrieved from GET Shipment.

Generally, only the GET tour request is needed. Depending on the workflow, the calculateTour and releaseTour endpoints may make sense. Creating tours via POST tour is not recommended — it is better to work with framework tours and automatic generation on import, which also allows dispatchers to spontaneously add properly configured tours.

In addition to the GET endpoints, the tour endpoint also allows various tour-specific actions to be triggered, such as calculating, optimizing, or releasing a tour.

Endpoints

POST /x4gateway/v1/import/tour

as well as
GET /x4gateway/v1/import/tour/{id} --> normal GET request by ID
GET /x4gateway/v1/import/tour --> GET request by RefID
GET /x4gateway/v1/import/tour/getId/{refId} --> find tour ID by tour RefID
GET /x4gateway/v1/import/tour/getshipments --> returns only the shipments contained in the tour. Deprecated, better use GET tour or the Shipment endpoint.
PUT /x4gateway/v1/import/tour --> UPDATE request by ID or RefID
DELETE /x4gateway/v1/import/tour/{id} --> normal DELETE request by ID

Additional endpoints for tour actions:
POST /x4gateway/v1/import/tour/{id}/appendShipment --> assigns the sent shipment to the tour
POST /x4gateway/v1/import/tour/{id}/appendShipments --> assigns the sent shipments to the tour
POST /x4gateway/v1/import/tour/allocateShipmentsToTour --> if shipments have already been imported they can be assigned by IDs
POST /x4gateway/v1/import/tour/{id}/calculateTour --> triggers tour calculation (response time can be several minutes depending on complexity)
POST /x4gateway/v1/import/tour/calculateTours --> triggers calculation of all tours by tour date (response time can be several minutes depending on complexity)
POST /x4gateway/v1/import/tour/{id}/optimizeTour --> triggers tour optimization (response time can be several minutes depending on complexity)
POST /x4gateway/v1/import/tour/optimizeTours --> triggers optimization of all tours by tour date (response time can be several minutes depending on complexity)
POST /x4gateway/v1/import/tour/{id}/releaseTour --> triggers tour release
POST /x4gateway/v1/import/tour/{id}/unreleaseTour --> triggers tour un-release

Request

{
	"refId": "string",
	"name": "string",
	"note": "string",
	"driverId": "string",						//typically either by ID
	"driverRefId": "string",					//or by RefID, not required
	"driver": {},								//when the driver is referenced as an object
	"vehicle": {},
	"trailer": {},
	"shipments": [{}],						//all shipments in the tour are created as new shipments
	"startVehiclePoi": {},						//vehicle start location
	"endVehiclePoi": {},						//vehicle end location
	"startDepotPoi": {},						//start depot
	"endDepotPoi": {},						//end depot
	"fixedTourStartTime": "2026-02-27T07:12:42.636Z",
	"fixStartTime": "string",					//in minutes
	"earliestTourStart": "string",				//in minutes
	"latestTourEnd": "string",					//in minutes
	"pickupDate": "2026-02-27T07:12:42.636Z",
	"fromDate": "2026-02-27T07:12:42.636Z",
	"tillDate": "2026-02-27T07:12:42.636Z",
	"generationModel": 0,						//tour generation model
	"isCommissioned": true,					//a commissioned tour cannot be calculated or optimized
	"attachments": [{}]
}

Used enums: Tour generation model.

Response

The response structure is analogous to the request structure; all information sent in the POST as well as system-supplemented information is returned.

The ID / tour ID is important information that should ideally be stored in the upstream system.