Ordini di trasporto / Spedizioni
L'ordine di trasporto è l'entità essenziale per la pianificazione e l'esecuzione delle spedizioni in X4fleet. Poiché l'entità è molto ampia, di seguito viene illustrata dapprima la sua struttura dati e poi i suoi segmenti più importanti.
Inoltre, la maggior parte delle proprietà è opzionale, poiché a seconda del caso d'uso non tutti i dati sono disponibili oppure vengono aggiunti solo in un secondo momento nel processo.
In linea di principio vale: prima il dispatcher conosce le informazioni rilevanti per il trasporto, meglio può pianificare in anticipo risorse come il veicolo e il conducente. La priorità è:
- Quando e dove deve essere caricato qualcosa
- Quando e dove deve essere scaricato questo qualcosa
- Quali quantità, volumi e pesi devono essere trasportati
- C'è qualcosa di particolare da osservare riguardo alle merci, alle sedi e durante il trasporto?
Endpoint
POST /x4gateway/v1/import/shipment
nonché
GET /x4gateway/v1/import/shipment/{id} --> normale richiesta GET tramite ID spedizione
GET /x4gateway/v1/import/shipment --> richiesta GET tramite RefID e/o data di spedizione e/o sistema sorgente
GET /x4gateway/v1/import/shipments --> richiesta GET tramite più RefID e/o sistema sorgente
DELETE /x4gateway/v1/import/shipment/{id} --> normale richiesta DELETE tramite ID spedizione
DELETE /x4gateway/v1/import/shipments --> richiesta DELETE tramite più ID spedizione
PUT /x4gateway/v1/import/shipment/{id} --> richiesta UPDATE tramite ID spedizione
PUT /x4gateway/v1/import/shipment --> richiesta UPDATE tramite RefID
Request
Poiché la struttura della richiesta viene utilizzata in modo diverso a seconda del caso d'uso, qui ci atteniamo all'applicazione di base. Diversi esempi di richiesta possono essere consultati e copiati più in basso.
Struttura di base / panoramica:
[
{
"id": 0, //ID spedizione (assegnato dal sistema)
"extOrderRefId": "string", //Riferimento dell'ordine dal cliente
"orderNumber": "string", //Ordine di vendita (può avere N spedizioni)
"refId": "string", //Riferimento di spedizione (p. es. dall'ERP)
"groupId": 0, //Se l'ordine deve andare in un sottogruppo specifico
"source": "string", //Sistema sorgente, sono ammessi gli stessi RefId da fonti diverse
"client": {[]}, //Cliente
"provider": {[]}, //Committente
"pickup": {[]}, //Luogo di ritiro
"dropoff": {[]}, //Luogo di consegna
"products": [{},], //Posizioni di spedizione / articoli
"datePickup": "datetime", //Data di ritiro/del giro prevista
"status": 0, //Stato della spedizione, ENUM
"fiscalStatus": 0, //Stato di fatturazione, ENUM
"note": "string", //Annotazione di spedizione, testo libero
"customField1": "string", //Campo personalizzato di spedizione, deve prima essere configurato nel backend
"specialities": [], //Specialità di spedizione, devono prima essere configurate nel backend
"skills": [{},], //Competenze del conducente, devono prima essere configurate nel backend
"checklists": [{},], //Liste di controllo rilevanti per la spedizione, devono prima essere configurate nel backend
"vehicleQualifications": [{},], //Qualifiche del veicolo, devono prima essere configurate nel backend
"agreedIncome": 0, //Ricavo concordato (sovrascrive la tariffa del vettore e i valori delle posizioni)
}
]Enumerazioni utilizzate: Stato della spedizione, FiscalStatus.
Client / Provider
Il committente (provider) ha inoltrato l'ordine di trasporto al mandante X4fleet. Il cliente è in relazione commerciale con il committente, non necessariamente con il mandante X4fleet. I costi per merci, servizi e trasporto vengono fatturati al committente.
Come esempio, il cliente ha ordinato un laptop presso il committente. Il committente incarica il cliente Xplanis del trasporto. Il laptop viene fatturato al cliente dal committente. Il cliente Xplanis fattura a sua volta il trasporto al committente.
I segmenti Provider (committente) e Client (cliente) sono simili nella struttura, tuttavia non in ogni ordine di trasporto è necessario anche un cliente, pertanto di seguito viene trattato solo Provider.
"provider": {
"id": 0, //ID partner commerciale (assegnato dal sistema)
"refId": "string", //ID partner commerciale dall'ERP
"organisation": "string",
"contactName": "string",
"name2": "string",
"clientNumber": "string",
"guSurchargePercent": 0, //Supplemento / sconto %
"guFuelSurchargePercent": 0, //Supplemento carburante %
"guLoadingToolSurchargePercent": 0, //Supplemento materiale di carico %
"guLoadingToolSurchargeFix": 0, //Supplemento materiale di carico assoluto
"phone1": "string",
"phone2": "string",
"email": "string",
"location": {
"id": 0, //assegnato dal sistema
"name": "string", //obsoleto/deprecated
"streetAddress": "string",
"postCode": "string",
"city": "string",
"countryCode": "string", //codice paese a 2 lettere p. es. CH
"coordinates": { //se non esiste alcun indirizzo o questo non è sufficientemente preciso
"lat": 47.193913278119449, //se non vengono inviate coordinate, l'indirizzo viene geocodificato automaticamente
"lng": 8.523516289875717
},
},
"language": "string", //DE, EN, FR, IT, ES
"contacts": [
{
"id": 0, //assegnato dal sistema
"refId": "string", //Riferimento alla persona di contatto dall'ERP
"contactName": "string",
"organisation": "string",
"...": "...", //analogo al partner commerciale
"isMainContact": true //questo contatto viene visualizzato per impostazione predefinita come persona di riferimento
}
],
"poBox": "string", //Casella postale
"fax": "string",
"web": "string"
}Per le persone di contatto valgono le stesse regole dei partner commerciali.
Pickup & Dropoff
Descrive il luogo in cui le merci vengono caricate/ritirate oppure scaricate/consegnate.
"pickup": {
"id": 0, //ID luogo di ritiro (assegnato dal sistema)
"shipmentLocation": { //Sede o indirizzo
"kind": 0, //Tipo di sede, ENUM
"name": "string",
"name2": "string",
"organization": "string",
"contactPhone": "string",
"contactPhone1": "string",
"contactPhone2": "string",
"email": "string",
"contacts": [], //Analogo al partner commerciale / persona di contatto
"location": {}, //Indirizzo della sede, analogo al partner commerciale
"start": "2025-03-28T15:02:55.359Z", //Da quando le merci possono essere ritirate
"end": "2025-03-28T15:02:55.359Z", //Fino a quando le merci possono essere ritirate
"notes": "string" //Annotazione di ritiro (visibile anche al conducente)
},
"dropoff": {}, //Analogo a PickupEnumerazioni utilizzate: Tipo di sede (kind).
Alla creazione di una spedizione, le annotazioni registrate nel luogo di ritiro o di consegna vengono aggiunte su una nuova riga all'annotazione di ritiro o di consegna (notes). I commenti disposizione dei luoghi vengono aggiunti al commento disposizione della spedizione (noteHiddenForDriver), prima quelli del luogo di ritiro, poi quelli del luogo di consegna. Le annotazioni vuote e i testi già contenuti nell'annotazione della spedizione non vengono aggiunti. All'aggiornamento di una spedizione esistente non vengono aggiunte annotazioni dei luoghi.
Tramite le proprietà start e end è possibile definire le finestre temporali in cui deve avvenire il ritiro o la consegna:
- Si indica da quando le merci possono essere ritirate (open end)
→ trasmettere solostart - Si indica fino a quando le merci devono essere ritirate (open
start)
→ trasmettere soloend - Viene indicata una finestra temporale fissa, entro la quale le merci devono essere ritirate (between)
→ trasmettere entrambi - Viene indicato un orario preciso, in cui esattamente le merci devono essere ritirate
→ trasmettere entrambi,starteenddevono avere lo stesso valore
Posizione dell'ordine & articolo
"products": [ // N posizioni dell'ordine
{
"id": 0, //ID posizione di spedizione (assegnato dal sistema)
"product": { //Articolo/servizio della posizione dell'ordine
"id": 0, //assegnato dal sistema
"refId": "string" //dal sistema del cliente, può fare riferimento ai dati anagrafici X4fleet per utilizzare articoli preconfigurati
"name": "string",
"type": "string", //Product, Service, Tool (materiale di carico), Container (collo)
"unit": "string", //vedere la descrizione
"notes": "string",
"description": "string",
"diameter": 0,
"palletCount": 0,
"weight": 0,
"volume": 0,
"width": 0,
"height": 0,
"length": 0,
"centiLiters": 0,
"squareCentimetersPerUnit": 0,
"loadingCentimeters": 0,
"storageLocation": "string",
"isVisibleOnApp": true,
"nameTranslation": {}, //Traduzione del nome dell'articolo DE, FR, IT, EN, ES
"descriptionTranslation": {}, //Traduzione della descrizione dell'articolo DE, FR, IT, EN, ES
"notesTranslation": {}, //Trad. dell'annotazione dell'articolo DE, FR, IT, EN, ES
"code": "string",
"isPilable": true,
},
"requiredQuantity": 0, //Quantità necessaria
"description": "string",
"sortOrder": 0, //Ordine di ordinamento, se necessario
"refStr": "string", //Riferimento al sistema del cliente p. es. posizione nell'ordine di vendita
"storageLocation": "string", //Postazione di magazzino/di preparazione
"barCode": "string",
"pickupNotes": "string",
"dropoffNotes": "string",
"totalPallets": 0, //Numero di pallet = pallet EUR 80x120cm
"totalWeight": 0, //Le dimensioni totali vengono calcolate automaticamente dai pesi singoli
"totalVolume": 0,
"totalCentiLiters": 0,
"totalSquareCentimetersPerUnit": 0,
"totalLoadingCentimeters": 0,
"totalPrice": 0,
"totalShippingPrice": 0,
"price": 0,
"isExplosive": true,
"isHazardous": true,
"isRefrigerated": true,
"isTire": true,
"code": "string" //p. es. codice articolo ERP
}
]È possibile rappresentare anche strutture di container, vedere Posizioni
Tutte le possibili unità di prodotto unit:
- Distanze
- Centimeters, Kilometer, LoadingMeters, Meters, Millimeter, RunningMeters
- Superfici
- SquareDecimeters, SquareMeters
- Volume
- CubicDecimeters, CubicCentimeter, CubicMeters, Deciliter, Liter
- Peso
- Gram, Kilo, Ton
- Tempo
- Days, Hours, Minutes
- Unità di spedizione & varie
- Apparat, Bag, Bale, Barrel, BigBag, Bottle, Bundle, Canister, Carton, Cartridge, Cassette, Coil, Colis, Container, Diverse, EinwegPalet, EuroPalet, Flat, Gitterbox, Halbpalet, Kettle, P10, P100, P20, P50, Packaging, Pair, Parcel, Plate, Pole, Poster, Ring, Set, Tin, Tube, Unit
Impostazioni di importazione per gli ordini di trasporto
Le seguenti impostazioni possono essere definite solo dagli amministratori Xplanis.
Tramite Impostazioni > Impostazioni > Importazione è possibile configurare il comportamento durante l'invio degli ordini di trasporto e il loro aggiornamento.
Le più utilizzate:
Rilascia automaticamente gli ordini- Spesso utile quando gli ordini di trasporto provenienti dal sistema del cliente non devono essere arricchiti con informazioni aggiuntive in X4fleet prima di essere disposti
Regola per l'aggiornamento delle spedizioniAggiornamento della spedizione possibile in qualsiasi momento- quindi anche quando la spedizione è già in esecuzione in un giro (non consigliato)La spedizione non può più essere aggiornata dopo l'assegnazione al giro- processo stabile a costo della flessibilità.La spedizione non può più essere aggiornata dopo il rilascio del giro- In caso di modifiche rilevanti al luogo di ritiro/consegna, alla data o alle quantità/volumi/pesi, una spedizione può "uscire" da un giro già pianificato. Ciò dovrebbe essere preso in considerazione solo se è garantita una buona comunicazione tra l'addetto dell'ordine di vendita e il dispatcher, poiché qui le modifiche possono mettere in disordine la pianificazione del dispatcher
Regola per l'eliminazione degli ordiniè la controparte di "Aggiornamento delle spedizioni"La spedizione non può più essere eliminata dopo l'assegnazione al giro..., dopo il rilascio del giro..., dopo l'avvio del giro..., dopo l'inizio del carico- A seconda del processo interno del cliente, di come vengono gestite le cancellazioni/i rinvii spontanei.
Response
La struttura della risposta è analoga alla struttura della richiesta, e tutte le informazioni che sono state inviate nel POST, nonché le informazioni aggiunte dal sistema, vengono restituite.
A tal riguardo, l'ID / ID spedizione è un'informazione importante che dovrebbe idealmente essere conservata nel sistema a monte.
Inoltre, la risposta contiene il campo troughProcessType (solo lettura). Per gli ordini cassone indica il tipo di processo: 0 = Place, 1 = Empty, 2 = Change, 3 = Fetch. Per le spedizioni senza ordine cassone il valore è null. Vedere anche Enums.
Esempi di richieste
[
{
"extOrderRefId": "ExtOrderRefId",
"orderNumber": "OrderNumber",
"provider": {
"refId": "XS0001",
"organisation": "Muster AG",
"contactName": "Max Muster",
"name2": "Anlieferung",
"phone1": "+41 61 123 45 67",
"email": "info@muster-ag.ch",
"location": {
"streetAddress": "Musterstrasse 1",
"postCode": "3006",
"city": "Bern",
"countryCode": "CH",
},
},
"pickup": {
"shipmentLocation": {
"kind": 0,
"name": "PickUp AG - Abholung",
"name2": "Maskus Muster",
"organization": "PickUp AG",
"contactPhone": "+41 78 765 43 21",
"email": "maskus.muster@pickup.com",
"location": {
"streetAddress": "Mustergasse 5",
"postCode": "4001",
"city": "Basel",
"countryCode": "CH",
},
"refId": "XS0002",
},
"start": "2025-04-15T00:00:00.000Z",
"end": "2025-04-20T00:00:00.000Z",
},
"dropoff": {
"shipmentLocation": {
"kind": 1,
"name": "Muster AG - Depot",
"name2": "Lager",
"organization": "Muster AG",
"location": {
"streetAddress": "Musterstrasse 1",
"postCode": "3006",
"city": "Bern",
"countryCode": "CH",
},
"refId": "XS0003",
},
"start": "2025-04-21T00:00:00.000Z",
"end": "2025-04-21T23:59:59.000Z",
},
"datePickup": "2025-04-15T12:41:08.524Z",
"refId": "L0001",
"source": "ERP1",
}
]Tramite RefId è possibile fare riferimento ai dati anagrafici esistenti. I valori trasmessi sovrascrivono i dati anagrafici. Se un RefId non è già stato registrato, viene creato temporaneamente o in modo permanente (a seconda dell'entità e dell'impostazione di importazione).
[
{
"extOrderRefId": "ExtOrderRefId",
"orderNumber": "OrderNumber",
"provider": {
"refId": "XS0001",
"organisation": "Muster AG",
"contactName": "Max Muster",
"name2": "Anlieferung",
"phone1": "+41 61 123 45 67",
"email": "info@muster-ag.ch",
"location": {
"streetAddress": "Musterstrasse 1",
"postCode": "3006",
"city": "Bern",
"countryCode": "CH"
}
},
"pickup": {
"shipmentLocation": {
"kind": 0,
"name": "PickUp AG - Abholung",
"name2": "Maskus Muster",
"organization": "PickUp AG",
"contactPhone": "+41 78 765 43 21",
"email": "maskus.muster@pickup.com",
"location": {
"streetAddress": "Mustergasse 5",
"postCode": "4001",
"city": "Basel",
"countryCode": "CH"
},
"refId": "XS0002"
},
"start": "2025-06-11T00:00:00.000Z",
"end": "2025-06-12T00:00:00.000Z"
},
"dropoff": {
"shipmentLocation": {
"kind": 1,
"name": "Muster AG - Depot",
"name2": "Lager",
"organization": "Muster AG",
"location": {
"streetAddress": "Musterstrasse 1",
"postCode": "3006",
"city": "Bern",
"countryCode": "CH"
},
"refId": "XS0003"
},
"start": "2025-06-12T00:00:00.000Z",
"end": "2025-06-13T00:00:00.000Z"
},
"products": [
{
"product": {
"refId": "ART10001",
},
"requiredQuantity": 5,
"totalWeight": 55000,
},
{
"product": {
"refId": "ART10002",
},
"requiredQuantity": 1,
}
],
"datePickup": "2025-06-11T12:41:08.524Z",
"refId": "L0001",
"source": "ERP1"
}
]È possibile trasmettere un numero qualsiasi di prodotti; se il prodotto può essere referenziato (tramite RefId), vengono utilizzati i dati anagrafici memorizzati in X4fleet. Valori specifici, come ad esempio il peso totale, possono essere sovrascritti. Se il prodotto con questo RefId non esiste, viene creato temporaneamente (o in modo permanente con la corrispondente impostazione di importazione).
[
{
"extOrderRefId": "ExtOrderRefId",
"orderNumber": "OrderNumber",
"provider": {
"refId": "XS0001",
"organisation": "Muster AG",
"contactName": "Max Muster",
"name2": "Anlieferung",
"phone1": "+41 61 123 45 67",
"email": "info@muster-ag.ch",
"location": {
"streetAddress": "Musterstrasse 1",
"postCode": "3006",
"city": "Bern",
"countryCode": "CH"
}
},
"pickup": {
"shipmentLocation": {
"kind": 0,
"name": "PickUp AG - Abholung",
"name2": "Maskus Muster",
"organization": "PickUp AG",
"contactPhone": "+41 78 765 43 21",
"email": "maskus.muster@pickup.com",
"location": {
"streetAddress": "Mustergasse 5",
"postCode": "4001",
"city": "Basel",
"countryCode": "CH"
},
"refId": "XS0002"
},
"start": "2025-06-11T00:00:00.000Z",
"end": "2025-06-12T00:00:00.000Z"
},
"dropoff": {
"shipmentLocation": {
"kind": 1,
"name": "Muster AG - Depot",
"name2": "Lager",
"organization": "Muster AG",
"location": {
"streetAddress": "Musterstrasse 1",
"postCode": "3006",
"city": "Bern",
"countryCode": "CH"
},
"refId": "XS0003"
},
"start": "2025-06-12T00:00:00.000Z",
"end": "2025-06-13T00:00:00.000Z"
},
"products": [
{
"product": {
"name": "Montage",
"type": "Service",
"unit": "Hours",
"notes": "auf 15min runden",
"description": "Montagezeit vor Ort",
"code": "SER10001",
"refId": "SER10001",
},
"requiredQuantity": 1,
"dropoffNotes": "auf 15min runden, nicht vergessen!",
}
],
"datePickup": "2025-06-11T12:41:08.524Z",
"refId": "L0001",
"source": "ERP1"
}
]Quando si utilizzano prodotti non predefiniti, è possibile impostare anche il tipo di prodotto. Per i tipi di prodotto disponibili, vedere l'elenco delle enumerazioni.
Messaggi di errore frequenti
- {"code":99,"messages":["There was an general error","SqlDateTime overflow. Must be between 1/1/1753 12:00:00 AM and 12/31/9999 11:59:59 PM."],"RequestId":null,"Id":0}
--> Data o formato data errato. Tutte le date devono essere indicate in UTC. - {"code":45,"messages":["Shipment has invalid pickup/dropoff dates. Shipment OrderNumber = XXX."],"RequestId":null,"Id":0}
--> Data o formato data errato. Tutte le date devono essere indicate in UTC. - {"code":45,"messages":["Shipment has invalid date. Pickup date should be before dropoff date. Shipment OrderNumber = XXX."],"RequestId":null,"Id":0}
--> La data di ritiro deve obbligatoriamente precedere la data di consegna. - {"code":99,"messages":["There was an general error","Product unit Days is not available for containers."],"RequestId":null,"Id":0}
--> Abbiamo diversi tipi di prodotto, e non tutte le unità di prodotto sono disponibili per tutti i tipi di prodotto (p. es. le ore non sono disponibili per i liquidi). Verificare l'enumerazione interessata, altrimenti contattare il nostro supporto. - {"code":7,"messages":["Shipment cannot be inserted because there is already one","property: RefId='XXX', Source='XXX'"],"RequestId":null,"Id":0}
--> I duplicati sono disattivati per questo gruppo, il RefID di spedizione deve essere univoco per ogni sistema sorgente (source).