Giro

Il giro raccoglie tutte le informazioni necessarie per evadere N spedizioni. Oltre alle spedizioni, queste includono informazioni sul veicolo/rimorchio, il conducente, il periodo e la data di esecuzione, le fermate, i punti di trasporto (incluse le attività per il conducente) nonché le liste di controllo e gli incidenti dell'intero giro.

A seconda che gli ordini di vendita nel sistema cliente siano o meno referenziati a un giro, le informazioni di esecuzione delle spedizioni possono essere recuperate anche singolarmente da GET Shipment.

In genere è necessaria solo la richiesta GET tour. A seconda del workflow, gli endpoint calculateTour e releaseTour possono avere senso. La creazione di giri tramite POST tour non è consigliata — è preferibile lavorare con giri quadro e generazione automatica all'importazione, che consente anche ai dispatcher di aggiungere spontaneamente giri già correttamente configurati.

Oltre agli endpoint GET, l'endpoint tour consente anche di attivare varie azioni specifiche del giro, come il calcolo, l'ottimizzazione o il rilascio.

Endpoint

POST /x4gateway/v1/import/tour

nonché
GET /x4gateway/v1/import/tour/{id} --> normale richiesta GET tramite ID
GET /x4gateway/v1/import/tour --> richiesta GET tramite RefID
GET /x4gateway/v1/import/tour/getId/{refId} --> trovare l'ID giro tramite RefID giro
GET /x4gateway/v1/import/tour/getshipments --> restituisce solo le spedizioni contenute nel giro. Obsoleto, meglio usare GET tour o l'endpoint Shipment.
PUT /x4gateway/v1/import/tour --> richiesta UPDATE tramite ID o RefID
DELETE /x4gateway/v1/import/tour/{id} --> normale richiesta DELETE tramite ID

Endpoint aggiuntivi per le azioni sul giro:
POST /x4gateway/v1/import/tour/{id}/appendShipment --> la spedizione inviata viene assegnata al giro
POST /x4gateway/v1/import/tour/{id}/appendShipments --> le spedizioni inviate vengono assegnate al giro
POST /x4gateway/v1/import/tour/allocateShipmentsToTour --> se le spedizioni sono già state importate, possono essere assegnate tramite ID
POST /x4gateway/v1/import/tour/{id}/calculateTour --> attiva il calcolo del giro (il tempo di risposta può essere di diversi minuti a seconda della complessità)
POST /x4gateway/v1/import/tour/calculateTours --> attiva il calcolo di tutti i giri tramite data giro (il tempo di risposta può essere di diversi minuti)
POST /x4gateway/v1/import/tour/{id}/optimizeTour --> attiva l'ottimizzazione del giro (il tempo di risposta può essere di diversi minuti)
POST /x4gateway/v1/import/tour/optimizeTours --> attiva l'ottimizzazione di tutti i giri tramite data giro (il tempo di risposta può essere di diversi minuti)
POST /x4gateway/v1/import/tour/{id}/releaseTour --> attiva il rilascio del giro
POST /x4gateway/v1/import/tour/{id}/unreleaseTour --> attiva il ritiro del rilascio

Request

{
	"refId": "string",
	"name": "string",
	"note": "string",
	"driverId": "string",						//di norma tramite ID
	"driverRefId": "string",					//oppure tramite RefID, non richiesto
	"driver": {},								//quando il conducente è referenziato come oggetto
	"vehicle": {},
	"trailer": {},
	"shipments": [{}],						//tutte le spedizioni nel giro vengono create come nuove spedizioni
	"startVehiclePoi": {},						//posizione di partenza del veicolo
	"endVehiclePoi": {},						//posizione finale del veicolo
	"startDepotPoi": {},						//deposito di partenza
	"endDepotPoi": {},						//deposito finale
	"fixedTourStartTime": "2026-02-27T07:12:42.636Z",
	"fixStartTime": "string",					//in minuti
	"earliestTourStart": "string",				//in minuti
	"latestTourEnd": "string",					//in minuti
	"pickupDate": "2026-02-27T07:12:42.636Z",
	"fromDate": "2026-02-27T07:12:42.636Z",
	"tillDate": "2026-02-27T07:12:42.636Z",
	"generationModel": 0,						//modello di generazione del giro
	"isCommissioned": true,					//un giro commissionato non può essere calcolato né ottimizzato
	"attachments": [{}]
}

Enumerazioni utilizzate: Modello di generazione del giro.

Response

La struttura della risposta è analoga alla struttura della richiesta; vengono restituite tutte le informazioni inviate nel POST nonché le informazioni integrate dal sistema.

L'ID / l'ID giro è un'informazione importante che dovrebbe idealmente essere memorizzata nel sistema sorgente.