Posizioni d'ordine / Articoli

Le posizioni d'ordine, denominate anche articoli o prodotti in X4Fleet, sono gli elementi effettivamente trasportati con la spedizione. I vari tipi come merci alla rinfusa, liquidi o servizi rientrano tutti in questa entità e endpoint.

Di norma, i dati anagrafici degli articoli vengono importati una volta all'inizio. Le spedizioni fanno poi riferimento agli articoli esistenti o utilizzano nuove posizioni che non vengono automaticamente create nei dati anagrafici. Per sincronizzare i dati anagrafici degli articoli tra il sistema sorgente e X4Fleet, è possibile utilizzare i seguenti endpoint:

Endpoint

POST /x4gateway/v1/import/product

nonché
GET /x4gateway/v1/import/product/{id} --> normale richiesta GET tramite ID
GET /x4gateway/v1/import/product --> richiesta GET tramite RefID
PUT /x4gateway/v1/import/product/{id} --> richiesta UPDATE tramite ID
DELETE /x4gateway/v1/import/product/{id} --> normale richiesta DELETE tramite ID

Request

POST product

{
	"name": "string",
	"hasVariants": true,						//obsoleto
	"type": "string",							//tipo articolo come stringa, vedi enumerazioni
	"unit": "string",							//unità, vedi enumerazioni
	"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",						//codice lingua a 2 lettere: de, en, fr, it, es
	"isVisibleOnApp": true,					//controlla la visibilità dell'articolo per i conducenti
	"specialities": [{}],
	"skills": [{}],							//competenze richieste per questo articolo
	"nameTranslation": {},					//Traduzione del nome dell'articolo DE, FR, IT, EN, ES
	"descriptionTranslation": {},				//Traduzione della descrizione dell'articolo DE, FR, IT, EN, ES
	"notesTranslation": {},					//Traduzione dell'annotazione dell'articolo DE, FR, IT, EN, ES
	"synonymNames": "string",					//obsoleto, rilevante solo per il workflow TSG
	"qualifications": [{}],
	"code": "string",							//numero articolo
	"isPilable": true,						//p.es. per lastre, rilevante per il calcolo dell'altezza massima
	"isStackable": true,						//p.es. per scatole, rilevante per il consumo di spazio
	"isFastCreatable": true,					//raramente utilizzato, rilevante solo per determinati workflow
	"skipDriverTaskCreationForPickup": true,	    //controlla la generazione di punti di trasporto
	"skipDriverTaskCreationForDropoff": true,    //controlla la generazione di punti di trasporto
	"bookkeepingAccount": {},				    //rilevante per la fatturazione
	"bookkeepingVatRate": {},					//rilevante per la fatturazione
	"productGroup": {},						//gruppo merci
	"refId": "string",
}

Enumerazioni utilizzate: Tipo articolo, Unità articolo.

POST shipment, sezione products

All'interno della struttura della spedizione, oltre all'articolo stesso (product), esiste la struttura completa Posizione (products). Una posizione d'ordine definisce una serie di attributi e contiene uno o più articoli. Molti attributi possono essere impostati sia a livello di posizione che a livello di articolo. Di seguito viene descritta questa struttura:

{
	"products": [
		{
			"product": {},						//vedi struttura sopra
			"requiredQuantity": 0,				//quantità da trasportare
			"description": "string",
			"sortOrder": 0,						//ordinamento, posizione nella lista
			"refStr": "string",					//RefID della posizione
			"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,			//rilevante solo per il workflow franco
			"vevaCodeNumber": "string",
			"transportationDocumentNumber": "string",			//rilevante solo per il workflow documenti di trasporto
			"skipDriverTaskCreationForPickupActual": true,
			"skipDriverTaskCreationForDropoffActual": true,
			"productGroup": {},
		}
	]
}

Tutte le dimensioni total vengono calcolate automaticamente dalle dimensioni individuali sull'articolo. I valori impostati esplicitamente sovrascrivono quelli calcolati automaticamente.

POST shipment, sezione products, struttura contenitore

X4Fleet può rappresentare anche strutture a contenitore, p.es. una gabbia di trasporto con più pacchi più piccoli al suo interno. Il conducente deve controllare solo il contenitore intero durante il carico. Tali strutture possono essere rappresentate come segue:

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

Il localContainerGuid può essere impostato durante l'importazione e deve essere un GUID valido (p.es. Guid.NewGuid();). È possibile referenziare qualsiasi tipo e numero di prodotti in un contenitore.

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