Sites : Lieu d'enlèvement / livraison

Les lieux d'enlèvement et de livraison sont désignés comme sites dans X4Fleet. Les nouveaux sites sont automatiquement importés et créés lors du POST Shipment. Si la saisie des commandes est effectuée manuellement ou si le catalogue des sites doit être synchronisé entre le système source et X4Fleet, les endpoints API suivants peuvent être utilisés.

Endpoints

POST /x4gateway/v1/import/poi

ainsi que
GET /x4gateway/v1/import/poi/{id} --> requête GET normale via ID de site
GET /x4gateway/v1/import/poi --> requête GET via RefID
GET /x4gateway/v1/import/pois --> recherche de sites selon divers paramètres avec pagination
DELETE /x4gateway/v1/import/poi/{id} --> requête DELETE normale via ID de site

Avec DELETE, seuls les sites de votre propre groupe principal peuvent être supprimés. Si le site appartient à un autre groupe principal, il n'est pas supprimé et l'API répond avec HTTP 400 et le code d'erreur 2. Lors de la suppression, les liens du site avec les partenaires commerciaux et avec les commanditaires de la commande web ainsi que les stocks du site sont supprimés. Le site lui-même est désactivé (et non supprimé définitivement).

Pour POST site et pour l'importation d'ordres également, seuls les ID de sites de votre propre groupe principal peuvent être utilisés. Si l'ID d'un site d'un autre groupe principal est transmis, l'importation échoue avec le message « Location with Id=… was not found. »

Request

{
	"clients": [
		{
			"refId": "string"					//les sites peuvent appartenir à des partenaires commerciaux, liés ici via RefID partenaire
		}
	],
	"kind": 0,								//type de site
	"name": "string",
	"askForSignature": true,
	"name2": "string",
	"organization": "string",
	"contactPhone": "string",
	"contactPhone1": "string",
	"contactPhone2": "string",
	"fax": "string",
	"driverImages": "string",					//photos du site pour les chauffeurs
	"driverTextInformation": "string",			//informations sur le site pour les chauffeurs
	"serviceProvisionNumber": "string",
	"openPickupTpOnlyOverBarCode": true,
	"openDropoffTpOnlyOverBarCode": true,
	"openPickupTpOnlyWhenNear": true,
	"openDropoffTpOnlyWhenNear": true,
	"nearToPickupTpDistance": 0,
	"nearToDropoffTpDistance": 0,
	"active": true,
	"allowUpdateOverGateway": true,			//par défaut true ; repris uniquement lors de la création du site
	"validFrom": "2026-02-26T14:59:08.057Z",
	"validUntil": "2026-02-26T14:59:08.057Z",
	"stopTimeMinutes": 0,
	"email": "string",
	"contacts": [{}],							//contacts du site, structure et règles comme pour les partenaires commerciaux
	"attachments": [{}],						//pièces jointes visibles par le dispatcher et le chauffeur
	"specialities": [{}],						//spécialités (p.ex. accessible uniquement avec quai de chargement)
	"loadingTools": [{}],						//moyens de chargement
    "location": {
        "name": "string",            //obsolète
        "streetAddress": "string",
        "postCode": "string",
        "city": "string",
        "countryCode": "string",     //code pays à 2 lettres, p.ex. CH, DE, FR
        "coordinates": {             //si aucune adresse n'existe ou n'est pas assez précise
            "lat": 47.193913,        //si aucune coordonnée n'est envoyée, l'adresse est automatiquement géocodée
            "lng": 8.5235162
        },
    },
	"advisingConfig": {},
	"poiDocument": {},
	"notes": "string",
	"dispatcherNotes": "string",		    	//notes non visibles pour les chauffeurs
	"refId": "string",						//important : si aucune RefID n'est définie, le site est traité comme nouveau et une RefID est générée automatiquement
}

Énumérations utilisées : Type de site.

Si une requête POST inclut un ID ou une RefID et qu'un site avec cet ID ou cette RefID existe déjà, il sera écrasé.

Avec allowUpdateOverGateway, vous définissez si un site peut être mis à jour ultérieurement via l'API. La valeur est true par défaut et n'est reprise que lors de la création du site ; pour un site existant, une valeur envoyée ne change rien. Si la valeur est false, les importations ultérieures ne modifient plus le site : les champs, l'adresse, les contacts, les spécialités et les moyens de chargement restent inchangés. Le champ est également disponible pour les sites envoyés dans une commande comme lieu d'enlèvement ou de livraison (shipmentLocation).

Les contacts du site (contacts) sont soumis aux mêmes champs et règles de mise à jour que les contacts des partenaires commerciaux.

Response

La structure de la réponse est analogue à la structure de la requête ; toutes les informations envoyées dans le POST ainsi que les informations complétées par le système sont renvoyées.

L'ID / l'ID de site est une information importante qui devrait idéalement être mémorisée dans le système source.

Messages d'erreur fréquents

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}
  --> Le site n'appartient pas à votre propre groupe principal et ne peut pas être supprimé.
• {"code":5,"messages":["Pickup / Dropoff with this id or refNr does not exist"],"RequestId":null,"Id":0}
  --> Il n'existe aucun site avec cet ID.

POST:

• {"code":99,"messages":["There was an general error","Location with Id=XXX was not found."],"RequestId":null,"Id":0}
  --> L'ID de site transmis appartient à un autre groupe principal.