Order Items / Articles

Order items, also called articles or products in X4Fleet, are the elements that are physically transported with the shipment. The various types such as bulk goods, liquids, or services all fall under this entity and endpoint.

Typically, the article master data is imported once at the beginning. Shipments then reference existing articles or use new items that are not automatically stored in the master data. To synchronize the article master data between the upstream system and X4Fleet, the following endpoints can be used:

Endpoints

POST /x4gateway/v1/import/product

as well as
GET /x4gateway/v1/import/product/{id} --> normal GET request by ID
GET /x4gateway/v1/import/product --> GET request by RefID
PUT /x4gateway/v1/import/product/{id} --> UPDATE request by ID
DELETE /x4gateway/v1/import/product/{id} --> normal DELETE request by ID

Request

POST product

{
	"name": "string",
	"hasVariants": true,						//deprecated
	"type": "string",							//article type as string, see enums
	"unit": "string",							//unit, see enums
	"notes": "string",
	"description": "string",
	"diameter": 0,
	"palletCount": 0,
	"weight": 0,
	"serviceTimeDepotPickupSecondsPerUnit": 0,
	"serviceTimeDepotDropoffSecondsPerUnit": 0,
	"serviceTimeSitePickupSecondsPerUnit": 0,
	"serviceTimeSiteDropoffSecondsPerUnit": 0,
	"volume": 0,
	"width": 0,
	"height": 0,
	"length": 0,
	"cargoAreaConsumption": 0,
	"centiLiters": 0,
	"squareCentimetersPerUnit": 0,
	"loadingCentimeters": 0,
	"storageLocation": "string",
	"vevaCodeNumber": "string",
	"language": "string",						//2-letter language code: de, en, fr, it, es
	"isVisibleOnApp": true,					//controls article visibility for drivers
	"specialities": [{}],
	"skills": [{}],							//required skills for this article
	"nameTranslation": {},					//Translation of article name DE, FR, IT, EN, ES
	"descriptionTranslation": {},				//Translation of article description DE, FR, IT, EN, ES
	"notesTranslation": {},					//Translation of article note DE, FR, IT, EN, ES
	"synonymNames": "string",					//deprecated, only relevant for TSG workflow
	"qualifications": [{}],
	"code": "string",							//article number
	"isPilable": true,						//e.g. for plates, relevant for max height calculation
	"isStackable": true,						//e.g. for boxes, relevant for space consumption
	"isFastCreatable": true,					//rarely used, only relevant for specific workflows
	"skipDriverTaskCreationForPickup": true,	    //controls transport point generation
	"skipDriverTaskCreationForDropoff": true,    //controls transport point generation
	"bookkeepingAccount": {},				    //relevant for invoicing
	"bookkeepingVatRate": {},					//relevant for invoicing
	"productGroup": {},						//product group
	"refId": "string",
}

Used enums: Article type, Article unit.

POST shipment, products section

Within the shipment structure, in addition to the actual article (product), there is the comprehensive structure Position (products). An order item defines a range of attributes and contains one or more articles. Many of the attributes can be set both at item level and at article level. The following further describes this structure:

{
	"products": [
		{
			"product": {},						//see structure above
			"requiredQuantity": 0,				//quantity to be transported
			"description": "string",
			"sortOrder": 0,						//sort order, position in the list
			"refStr": "string",					//RefID of the item
			"storageLocation": "string",
			"barCode": "string",
			"pickupNotes": "string",
			"dropoffNotes": "string",
			"totalPallets": 0,
			"totalServiceTimeDepotPickupSecondsPerUnit": 0,
			"totalServiceTimeDepotDropoffSecondsPerUnit": 0,
			"totalServiceTimeSiteDropoffSecondsPerUnit": 0,
			"totalServiceTimeSitePickupSecondsPerUnit": 0,
			"totalWeight": 0,
			"totalVolume": 0,
			"totalCentiLiters": 0,
			"totalSquareCentimetersPerUnit": 0,
			"totalLoadingCentimeters": 0,
			"totalPrice": 0,
			"totalShippingPrice": 0,
			"price": 0,
			"isExplosive": true,
			"isHazardous": true,
			"isRefrigerated": true,
			"isTire": true,
			"code": "string",
			"serialNumber": "string",
			"inventoryNumber": "string",
			"bookkeepingAccount": {},
			"bookkeepingVatRate": {},
			"isQuantityRecalculatable": true,
			"isFrancoPosition": true,			//only relevant for franco workflow
			"vevaCodeNumber": "string",
			"transportationDocumentNumber": "string",			//only relevant for transport documents workflow
			"skipDriverTaskCreationForPickupActual": true,
			"skipDriverTaskCreationForDropoffActual": true,
			"productGroup": {},
		}
	]
}

All total dimensions are automatically calculated from the individual dimensions on the article. Explicitly set values override automatically calculated ones.

POST shipment, products section, container structure

X4Fleet can also represent container structures, e.g. a transport cage with several smaller packages inside. The driver only needs to check the entire container when loading, not each individual package. Such structures can be represented as follows:

{
	"products": [
		{
			"product": {},
			"refStr": "Container",
			"localContainerGuid": "40f36433-d274-42c0-966a-7eacafd61887",
		},
		{
			"product": {},
			"refStr": "Package1",
			"referenceToContainer": "40f36433-d274-42c0-966a-7eacafd61887",
		},
		{
			"product": {},
			"refStr": "Package2",
			"referenceToContainer": "40f36433-d274-42c0-966a-7eacafd61887",
		}
	]
}

The localContainerGuid can be set during import and must be a valid GUID (e.g. Guid.NewGuid();). Any product types and number of products can be referenced in a container.

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 is important information that should ideally be stored in the upstream system.