Sedi: Luogo di ritiro / consegna

I luoghi di ritiro e consegna sono denominati sedi in X4Fleet. Le nuove sedi vengono importate e create automaticamente durante il POST Shipment. Se la registrazione degli ordini avviene manualmente o se il catalogo delle sedi deve essere sincronizzato tra il sistema sorgente e X4Fleet, è possibile utilizzare i seguenti endpoint API.

Endpoint

POST /x4gateway/v1/import/poi

nonché
GET /x4gateway/v1/import/poi/{id} --> normale richiesta GET tramite ID sede
GET /x4gateway/v1/import/poi --> richiesta GET tramite RefID
GET /x4gateway/v1/import/pois --> ricerca sedi tramite vari parametri con funzione di paginazione
DELETE /x4gateway/v1/import/poi/{id} --> normale richiesta DELETE tramite ID sede

Con DELETE è possibile eliminare solo le sedi del proprio gruppo principale. Se la sede appartiene a un altro gruppo principale, non viene eliminata e l'API risponde con HTTP 400 e codice di errore 2. All'eliminazione vengono rimossi i collegamenti della sede con i partner commerciali e con i committenti dell'ordinazione web, nonché le giacenze della sede. La sede stessa viene disattivata (non eliminata definitivamente).

Anche con POST sede e con l'importazione di ordini è possibile utilizzare solo ID di sedi del proprio gruppo principale. Se viene inviato l'ID di una sede di un altro gruppo principale, l'importazione non riesce e restituisce il messaggio "Location with Id=… was not found."

Request

{
	"clients": [
		{
			"refId": "string"					//le sedi possono appartenere a partner commerciali, collegati qui tramite RefID partner
		}
	],
	"kind": 0,								//tipo di sede
	"name": "string",
	"askForSignature": true,
	"name2": "string",
	"organization": "string",
	"contactPhone": "string",
	"contactPhone1": "string",
	"contactPhone2": "string",
	"fax": "string",
	"driverImages": "string",					//foto della sede per i conducenti
	"driverTextInformation": "string",			//informazioni sulla sede per i conducenti
	"serviceProvisionNumber": "string",
	"openPickupTpOnlyOverBarCode": true,
	"openDropoffTpOnlyOverBarCode": true,
	"openPickupTpOnlyWhenNear": true,
	"openDropoffTpOnlyWhenNear": true,
	"nearToPickupTpDistance": 0,
	"nearToDropoffTpDistance": 0,
	"active": true,
	"allowUpdateOverGateway": true,			//predefinito true; applicato solo alla creazione della sede
	"validFrom": "2026-02-26T14:59:08.057Z",
	"validUntil": "2026-02-26T14:59:08.057Z",
	"stopTimeMinutes": 0,
	"email": "string",
	"contacts": [{}],							//contatti della sede, struttura e regole come per i partner commerciali
	"attachments": [{}],						//allegati visibili a dispatcher e conducente
	"specialities": [{}],						//specialità (p.es. accessibile solo con rampa di carico)
	"loadingTools": [{}],						//mezzi di carico
    "location": {
        "name": "string",            //obsoleto
        "streetAddress": "string",
        "postCode": "string",
        "city": "string",
        "countryCode": "string",     //codice paese a 2 lettere, p.es. CH, DE, FR
        "coordinates": {             //se non esiste un indirizzo o non è sufficientemente preciso
            "lat": 47.193913,        //se non vengono inviate coordinate, l'indirizzo viene geocodificato automaticamente
            "lng": 8.5235162
        },
    },
	"advisingConfig": {},
	"poiDocument": {},
	"notes": "string",
	"dispatcherNotes": "string",		    	//note non visibili ai conducenti
	"refId": "string",						//importante: se non viene impostata una RefID, la sede viene interpretata come nuova e viene generata automaticamente una RefID
}

Enumerazioni utilizzate: Tipo di sede.

Se una richiesta POST include un ID o una RefID e una sede con tale ID o RefID esiste già, questa verrà sovrascritta.

Con allowUpdateOverGateway si stabilisce se una sede può essere aggiornata successivamente tramite l'API. Il valore è true per impostazione predefinita e viene applicato solo quando la sede viene creata; per una sede esistente, un valore inviato non ha alcun effetto. Se il valore è false, le importazioni successive non modificano più la sede: campi, indirizzo, contatti, specialità e mezzi di carico restano invariati. Il campo è disponibile anche per le sedi inviate in un ordine come luogo di ritiro o di consegna (shipmentLocation).

Per i contatti della sede (contacts) valgono gli stessi campi e le stesse regole di aggiornamento dei contatti dei partner commerciali.

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 sede è un'informazione importante che dovrebbe idealmente essere memorizzata nel sistema sorgente.

Messaggi di errore frequenti

GET:

• {"code":5,"messages":["Pickup / Dropoff with this id or refNr does not exist"],"RequestId":null,"Id":0}

DELETE:

• {"code":2,"messages":["X4FleetGroupId is wrong for this Pickup / Dropoff."],"RequestId":null,"Id":0}
  --> La sede non appartiene al proprio gruppo principale e non può essere eliminata.
• {"code":5,"messages":["Pickup / Dropoff with this id or refNr does not exist"],"RequestId":null,"Id":0}
  --> Non esiste alcuna sede con questo ID.

POST:

• {"code":99,"messages":["There was an general error","Location with Id=XXX was not found."],"RequestId":null,"Id":0}
  --> L'ID sede inviato appartiene a un altro gruppo principale.