Auftragspositionen / Artikel

Auftragspositionen, in X4Fleet auch Artikel oder Produkt genannt, sind die Elemente, welche mit der Sendung effektiv transportiert werden. Dabei fallen die verschiedenen Arten wie Schütt-, Flüssiggut oder Service alle unter diese Entität und Endpunkt.

In der Regel wird der Artikelstamm zu Beginn einmalig ins X4Fleet importiert. Danach referenzieren Sendungen auf die existierenden Artikel oder verwenden neue Positionen, welche aber nicht automatisch in den Stammdaten angelegt werden. Soll der Artikelstamm zwischen Vorsystem und X4Fleet synchronisiert werden, können die folgenden Endpunkte verwendet werden:

Endpunkte

POST /x4gateway/v1/import/product

sowie
GET /x4gateway/v1/import/product/{id} --> normaler GET Request mittels ID
GET /x4gateway/v1/import/product --> GET Request mittels RefID
PUT /x4gateway/v1/import/product/{id} --> UPDATE Request mittels ID
DELETE /x4gateway/v1/import/product/{id} --> normaler DELETE Request mittels ID

Request

POST product

{
	"name": "string",
	"hasVariants": true,						//veraltet
	"type": "string",							//Artikeltyp als String, siehe Enum's
	"unit": "string",							//Einheit, siehe Enum's
	"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-stelliger Sprachcode: de, en, fr, it, es
	"isVisibleOnApp": true,					//Steuert Sichtbarkeit des Artikels für die Fahrer
	"specialities": [{}],
	"skills": [{}],							//Benötigte Fähigkeiten für diesen Artikel
	"nameTranslation": {},					//Übersetzung Artikelname DE, FR, IT, EN, ES
	"descriptionTranslation": {},				//Übersetzung Artikelbeschreibung DE, FR, IT, EN, ES
	"notesTranslation": {},					//Übersetzung Artikelbemerkung DE, FR, IT, EN, ES
	"synonymNames": "string",					//veraltet, nur relevant für TSG-Workflow
	"qualifications": [{}],
	"code": "string",							//Artikelnummer
	"isPilable": true,						//zB. bei Platten, relevant für die maximale Höhenberechnung
	"isStackable": true,						//zB. bei Boxen, relevant für den Platzverbrauch
	"isFastCreatable": true,					//selten verwendet, nur relevant für bestimmte Workflows
	"skipDriverTaskCreationForPickup": true,	    //Steuert TP Generierung
	"skipDriverTaskCreationForDropoff": true,    //Steuert TP Generierung
	"bookkeepingAccount": {},				    //relevant für Rechnungsstellung
	"bookkeepingVatRate": {},					//relevant für Rechnungsstellung
	"productGroup": {},						//Warengruppe
	"refId": "string",
}

Verwendete Enum's: Artikeltyp, Artikeleinheit.

POST shipment, Abschnitt products

Innerhalb der Sendungsstruktur gibt es neben dem eigentlichen Artikel (product) die umfassende Struktur Position (products). Eine Artikelposition definiert eine Reihe an Attributen, und enthält einen oder mehrere Artikel. Viele der Attribute können sowohl auf Ebene Position als auch auf Ebene Artikel gesetzt werden. Folgend gehen wir auf diese Struktur weiter ein:

{
	"products": [
		{
			"product": {},						//siehe Struktur oben
			"requiredQuantity": 0,				//zu transportierende Menge
			"description": "string",
			"sortOrder": 0,						//Sortierung, an welcher Position die Artikelposition stehen soll
			"refStr": "string",					//RefID der Position
			"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,			//nur relevant für Franko-Workflow
			"vevaCodeNumber": "string",
			"transportationDocumentNumber": "string",			//nur relevant für Transportdokumente-Workflow
			"skipDriverTaskCreationForPickupActual": true,
			"skipDriverTaskCreationForDropoffActual": true,
			"productGroup": {},
		}
	]
}

Alle total-Dimensionen werden automatisch aus den Einzeldimensionen auf dem Artikel hochgerechnet. Explizit gesetzte Werte übersteuern automatisch berechnete.

POST shipment, Abschnitt products, Containerstruktur

Im X4Fleet können auch Containerstrukturen abgebildet werden, also zB. ein Transportkäfig mit mehreren kleineren Packeten darin. Den Fahrer interessiert beim Laden somit zB. nur der gesamte Container, und muss nicht jedes einzelne Paket prüfen. Solche Strukturen können wie folgt abgebildet werden:

{
	"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",
		}
	]
}

Die localContainerGuid kann beim Import gesetzt werden und muss eine gültige GUID sein (zB. Guid.NewGuid();). Es können beliebige Produkttypen und Anzahl an Produkten in einen Container referenziert werden.

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 eine wichtige Information, die ideallerweise im Vorsystem gemerkt wird.