Stellen: Abhol- / Zustellort

Abhol- und Zustellorte werden in X4Fleet als Stellen bezeichnet. Neue Stellen werden bei POST Shipment automatisch importiert und angelegt. Wenn die Auftragserfassung jedoch manuell erfolgt oder wenn der Stellenkatalog zwischen Vorsystem und X4Fleet synchronisiert werden soll, können die folgenden Endpunkte der API verwendet werden.

Endpunkte

POST /x4gateway/v1/import/poi

sowie
GET /x4gateway/v1/import/poi/{id} --> normaler GET Request mittels Stellen-ID
GET /x4gateway/v1/import/poi --> GET Request mittels RefID
GET /x4gateway/v1/import/pois --> Stellensuche anhand diverser Parameter mit Pagination-Funktion
DELETE /x4gateway/v1/import/poi/{id} --> normaler DELETE Request mittels Stellen-ID

Mit DELETE können nur Stellen der eigenen Hauptgruppe gelöscht werden. Gehört die Stelle zu einer anderen Hauptgruppe, wird sie nicht gelöscht und die API antwortet mit HTTP 400 und Fehlercode 2. Beim Löschen werden die Verknüpfungen der Stelle zu Geschäftspartnern und zu Bestellern der Webbestellung sowie die Lagerbestände der Stelle entfernt. Die Stelle selbst wird deaktiviert (nicht endgültig gelöscht).

Auch bei POST Stelle und beim Import von Aufträgen können nur Stellen-IDs der eigenen Hauptgruppe verwendet werden. Wird die ID einer Stelle einer anderen Hauptgruppe mitgesendet, schlägt der Import mit der Meldung "Location with Id=… was not found." fehl.

Request

{
	"clients": [
		{
			"refId": "string"					//Stellen können Geschäftspartner zugehören, diese können hier mittels Geschäftspartner-RefID verknüpft werden
		}
	],
	"kind": 0,								//Stellenart
	"name": "string",
	"askForSignature": true,					
	"name2": "string",
	"organization": "string",
	"contactPhone": "string",
	"contactPhone1": "string",
	"contactPhone2": "string",
	"fax": "string",
	"driverImages": "string",					//Stellenfotos für die Fahrer
	"driverTextInformation": "string",			//Stelleninfos für die Fahrer
	"serviceProvisionNumber": "string",
	"openPickupTpOnlyOverBarCode": true,
	"openDropoffTpOnlyOverBarCode": true,
	"openPickupTpOnlyWhenNear": true,
	"openDropoffTpOnlyWhenNear": true,
	"nearToPickupTpDistance": 0,
	"nearToDropoffTpDistance": 0,
	"active": true,
	"allowUpdateOverGateway": true,			//Standard true; wird nur beim Anlegen der Stelle übernommen
	"validFrom": "2026-02-26T14:59:08.057Z",
	"validUntil": "2026-02-26T14:59:08.057Z",
	"stopTimeMinutes": 0,
	"email": "string",
	"contacts": [{}],							//Stellenkontakte, Aufbau und Regeln wie bei den Geschäftspartnern
	"attachments": [{}],						//Anhänge, welche sowohl Disponent und Fahrer sehen
	"specialities": [{}],						//Spezialitäten (zB. nur mit Laderampe anfahrbar)
	"loadingTools": [{}],						//Ladehilfsmittel
    "location": {
        "name": "string",            //veraltet/depricated
        "streetAddress": "string",
        "postCode": "string",
        "city": "string",
        "countryCode": "string",     //2-stelliger Ländercode z.B. CH, DE, FR
        "coordinates": {             //falls keine Adresse existiert oder diese nicht präzise genug ist
            "lat": 47.193913,        //falls keine Koordinaten gesendet werden wird die Adresse automatisch geocodiert
            "lng": 8.5235162
        },
    },
	"advisingConfig": {},
	"poiDocument": {},
	"notes": "string",
	"dispatcherNotes": "string",		    	//Notizen, welche für die Fahrer nicht sichtbar sind
	"refId": "string",						//Wichtig, falls keine RefID gesetzt wird, wird die Stelle als neue Stelle interpretiert und eine RefID automatisch generiert
}

Verwendete Enum's: Stellenart.

Falls im POST Request eine ID oder RefID mitgegeben wird und eine Stelle mit dieser ID oder RefID bereits existiert wird diese überschrieben.

Mit allowUpdateOverGateway wird festgelegt, ob eine Stelle später über die API aktualisiert werden darf. Der Wert ist standardmässig true und wird nur übernommen, wenn die Stelle neu angelegt wird; bei einer bestehenden Stelle ändert ein mitgesendeter Wert nichts. Ist der Wert false, verändern spätere Importe die Stelle nicht mehr: Felder, Adresse, Kontakte, Spezialitäten und Ladehilfsmittel bleiben unverändert. Das Feld steht auch bei den Stellen zur Verfügung, die in einem Auftrag als Abhol- oder Zustellort mitgesendet werden (shipmentLocation).

Für die Stellenkontakte (contacts) gelten dieselben Felder und Aktualisierungsregeln wie für die Kontakte der Geschäftspartner.

Response

Die Response-Struktur ist analog der Request-Struktur, und alle Informationen welche im POST gesendet wurden, sowie vom System ergänzte Informationen, werden zurückgemeldet.

Dabei ist die ID / Stellen-ID eine wichtige Information, die ideallerweise im Vorsystem gemerkt wird.

Häufige Fehlermeldungen

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}
  --> Die Stelle gehört nicht zur eigenen Hauptgruppe und kann nicht gelöscht werden.
• {"code":5,"messages":["Pickup / Dropoff with this id or refNr does not exist"],"RequestId":null,"Id":0}
  --> Es existiert keine Stelle mit dieser ID.

POST:

• {"code":99,"messages":["There was an general error","Location with Id=XXX was not found."],"RequestId":null,"Id":0}
  --> Die mitgesendete Stellen-ID gehört zu einer anderen Hauptgruppe.