Transportaufträge / Sendungen
Der Transportauftrag ist die wesentliche Entität zur Planung und Erfüllung von Sendungen in X4fleet. Da die die Entität sehr umfangreich ist, wird folgend auf ihre Datenstruktur und dann auf die wichtigsten Segmente eingegangen.
Weiter sind die meisten Eigenschaften optional, da je nach Anwendungsfall nicht alle Daten zur Verfügung stehen oder erst später im Prozess ergänzt werden.
Grundsätzlich gilt, je früher der Disponent für den Transport relevante Informationen kennt, um so besser kann er Ressourcen wie Fahrzeug und Fahrer im Vorfeld planen. Priorität hat:
- Wann soll wo etwas aufgeladen werden
- Wann soll dieses etwas wo abgeladen werden
- Welche Mengen, Volumen, Gewichte sollen transportiert werden
- Gibt es bei Waren, Stellen und während des Transports etwas speziell zu beachten?
Endpunkte
POST /x4gateway/v1/import/shipment
sowie
GET /x4gateway/v1/import/shipment/{id} --> normaler GET Request mittels Sendungs-ID
GET /x4gateway/v1/import/shipment --> GET Request mittels RefID und/oder Sendungsdatum und/oder Quellsystem
GET /x4gateway/v1/import/shipments --> GET Request mittels mehrerer RefID's und/oder Quellsystem
DELETE /x4gateway/v1/import/shipment/{id} --> normaler DELETE Request mittels Sendungs-ID
DELETE /x4gateway/v1/import/shipments --> DELETE Request mittels mehrerer Sendungs-ID's
PUT /x4gateway/v1/import/shipment/{id} --> UPDATE Request mittels Sendungs-ID
PUT /x4gateway/v1/import/shipment --> UPDATE Request mittels RefID
Request
Da die Request-Strucktur je nach Anwendungsfall unterschiedlich verwendet wird, bleiben wir hier bei der Basisanwendung. Unterschiedliche Beispiel-Request können weiter unten eingesehen und kopiert werden.
Grundstruktur / Übersicht:
[
{
"id": 0, //Sendungs ID (vom System vorgegeben)
"extOrderRefId": "string", //Auftragsrefrenz vom Kunden
"orderNumber": "string", //Verkaufsauftrag (kann N Sendungen haben)
"refId": "string", //Sendungsreferenz (z.B. vom ERP)
"groupId": 0, //Wenn Auftrag in eine spezifische Subgruppe soll
"source": "string", //Quellsystem, es werden gleiche RefIds von unterschiedlichen Quellen erlaubt
"client": {[]}, //Kunde
"provider": {[]}, //Auftraggeber
"pickup": {[]}, //Abholort
"dropoff": {[]}, //Zustellort
"products": [{},], //Sendungspositionen / Artikel
"datePickup": "datetime", //Geplantes Abhol-/Tourdatum
"status": 0, //Sendungsstatus, ENUM
"fiscalStatus": 0, //Verrechnungsstatus, ENUM
"note": "string", //Sendungsbemerkung, Freitext
"customField1": "string", //Sendungs-CustomField, muss zuerst im Backend konfiguriert werden
"specialities": [], //Sendungsspezialitäten, müssen zuerst im Backend konfiguriert werden
"skills": [{},], //Fahrer-Fähigkeiten, müssen zuerst im Backend konfiguriert werden
"checklists": [{},], //Sendungsrelevante Checklisten, müssen zuerst im Backend konfiguriert werden
"vehicleQualifications": [{},], //Fahrzeugqualifikationen, müssen zuerst im Backend konfiguriert werden
"agreedIncome": 0, //Vereinbarter Ertrag (übersteuert GU-Tarif und Positionswerte)
}
]Verwendete Enum's: Sendungsstatus, FiscalStatus.
Client / Provider
Der Auftraggeber hat beim X4fleet-Mandanten den Transportauftrag eingereicht. Der Kunde steht in Geschäftsbeziehung zum Auftraggeber, nicht zwingend zum X4fleet-Mandanten. An den Auftraggeber werden Aufwände für Waren, Dienstleistungen und Transport verrechnet.
Als Beispiel hat der Kunde beim Auftraggeber einen Laptop bestellt. Der Auftraggeber beauftragt den Xplanis-Kunden mit dem Transport. Der Laptop wird durch den Auftraggeber dem Kunden in Rechnung gestellt. Der Xplanis-Kunde stellt dafür den Transport beim Auftraggeber in Rechnung.
Das Segment Provider (Auftraggeber) und Client (Kunde) sind sich im Aufbau ähnlich, jedoch wird nicht in jedem Transportauftrag auch ein Kunde benötigt, daher wird folgend nur auf Provider eingegangen.
"provider": {
"id": 0, //Geschäftspartner ID (vom System vorgegeben)
"refId": "string", //Geschäftspartner ID aus ERP
"organisation": "string",
"contactName": "string",
"name2": "string",
"clientNumber": "string",
"guSurchargePercent": 0, //Zuschlag / Rabatt %
"guFuelSurchargePercent": 0, //Treibstoffzuschlag %
"guLoadingToolSurchargePercent": 0, //Zuschlag Ladehilfsmittel %
"guLoadingToolSurchargeFix": 0, //Zuschlag Ladehilfsmittel absolut
"phone1": "string",
"phone2": "string",
"email": "string",
"location": {
"id": 0, //vom System vergeben
"name": "string", //veraltet/depricated
"streetAddress": "string",
"postCode": "string",
"city": "string",
"countryCode": "string", //2-stelliger Ländercode z.B. CH
"coordinates": { //falls keine Adresse existiert oder diese nicht präzise genug ist
"lat": 47.193913278119449, //falls keine Koordinaten gesendet werden wird die Adresse automatisch geocodiert
"lng": 8.523516289875717
},
},
"language": "string", //DE, EN, FR, IT, ES
"contacts": [
{
"id": 0, //vom System vergeben
"refId": "string", //Refrenz zur Kontaktperson aus ERP
"contactName": "string",
"organisation": "string",
"...": "...", //analog zum Geschäftspartner
"isMainContact": true //dieser Kontakt wird per Standard als Ansprechperson angezeigt
}
],
"poBox": "string", //Postfach
"fax": "string",
"web": "string"
}Für Kontaktpersonen gelten dieselben Regeln wie bei den Geschäftspartnern.
Pickup & Dropoff
Beschreibt den Ort an welchem Waren aufgeladen/abgeholt bzw. abgeladen/zugestellt werden.
"pickup": {
"id": 0, //Abholort ID (vom System vergeben)
"shipmentLocation": { //Stelle bzw. Adresse
"kind": 0, //Art der Stelle, ENUM
"name": "string",
"name2": "string",
"organization": "string",
"contactPhone": "string",
"contactPhone1": "string",
"contactPhone2": "string",
"email": "string",
"contacts": [], //Analog zu Geschäftspartner / Kontaktperson
"location": {}, //Adresse der Stelle, analog Geschäftspartner
"start": "2025-03-28T15:02:55.359Z", //Ab wann kann Ware abgeholt werden
"end": "2025-03-28T15:02:55.359Z", //Bis wann kann Ware abgeholt werden
"notes": "string" //Abholbemerkung (auch für Fahrer ersichtlich)
},
"dropoff": {}, //Analog zu PickupVerwendete Enum's: Stellenart (kind).
Beim Erstellen einer Sendung werden die Bemerkungen, die bei der Stelle des Abhol- bzw. Zustellorts hinterlegt sind, auf einer neuen Zeile an die Abhol- bzw. Zustellbemerkung (notes) angehängt. Die Dispobemerkungen der Stellen werden an die Dispobemerkung der Sendung (noteHiddenForDriver) angehängt, zuerst jene des Abholorts, dann jene des Zustellorts. Leere Bemerkungen und Texte, die bereits in der Sendungsbemerkung enthalten sind, werden nicht angehängt. Beim Aktualisieren einer bestehenden Sendung werden keine Bemerkungen der Stellen angehängt.
Via den Eigenschaften start und end können Zeitfenster in welchen die Abholung bzw. Zustellung erfolgen soll, definiert werden:
- Es wird vorgegeben ab wann Waren geholt werden können (open end)
→ nurstartmitgeben - Es wird vorgegeben bis wann Waren abgeholt sein müssen (open
start)
→ nurendmitgeben - Es wird ein fixes Zeitfenster vorgegeben, in welchem die Waren abgeholt werden müssen (between)
→ beides mitgeben - Es wird eine genaue Zeit vorgegeben, zu welcher genau die Waren abgeholt werden müssen
→ beides mitgeben,startundendmüssen den selben Wert haben
Auftragsposition & Artikel
"products": [ // N Auftragspositionen
{
"id": 0, //ID Sendungsposition (vom System vergeben)
"product": { //Artikel/Dienstleistung der Auftragsposition
"id": 0, //vom System vergeben
"refId": "string" //vom Kundensystem, kann auf X4fleet Stammdaten referenzieren um vorkonfigurierte Artikel zu verwenden
"name": "string",
"type": "string", //Product, Service, Tool (Lademittel), Container (Packstück)
"unit": "string", //siehe Beschreibung
"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": {}, //Übersetzung Artikelname DE, FR, IT, EN, ES
"descriptionTranslation": {}, //Übersetzung Artikelbeschreibung DE, FR, IT, EN, ES
"notesTranslation": {}, //Übr. Art.Bemerkung DE, FR, IT, EN, ES
"code": "string",
"isPilable": true,
},
"requiredQuantity": 0, //Benötigte Menge
"description": "string",
"sortOrder": 0, //Sortierreiehnfolge, falls nötig
"refStr": "string", //Refrenz zu Kundensystem z.B. Position im Verkaufsauftrag
"storageLocation": "string", //Lager-/Kommissionierplatz
"barCode": "string",
"pickupNotes": "string",
"dropoffNotes": "string",
"totalPallets": 0, //Anzahl Pallets = EUR-Palette 80x120cm
"totalWeight": 0, //Total Dimensionen werden automatisch aus den Einzelgewichten errechnet
"totalVolume": 0,
"totalCentiLiters": 0,
"totalSquareCentimetersPerUnit": 0,
"totalLoadingCentimeters": 0,
"totalPrice": 0,
"totalShippingPrice": 0,
"price": 0,
"isExplosive": true,
"isHazardous": true,
"isRefrigerated": true,
"isTire": true,
"code": "string" //z.B. Artikelcode ERP
}
]Es können auch Containerstrukturen abgebildet werden, siehe Positionen
Alle möglichen Produkt-Einheiten unit:
- Distanzen
- Centimeters, Kilometer, LoadingMeters, Meters, Millimeter, RunningMeters
- Flächen
- SquareDecimeters, SquareMeters
- Volumen
- CubicDecimeters, CubicCentimeter, CubicMeters, Deciliter, Liter
- Gewicht
- Gram, Kilo, Ton
- Zeit
- Days, Hours, Minutes
- Versandeinheiten & Divers
- 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
Import-Einstellungen für Transportaufträge
Folgende Einstellungen können nur durch die Xplanis Administratoren gesetzt werden.
Via Einstellungen > Einstellungen > Import kann das Verhalten beim Senden von Transportaufträgen und Aktualisieren dieser, konfiguriert werden.
Die am meisten verwendeten:
Automatisch Aufträge freigeben- Ist oft sinnvoll, wenn Transportaufträge welche aus dem Kundensystem kommen, nicht noch mit zusätzlichen Informationen in X4fleet angereichert werden müssen, bevor diese disponiert werden
Regel zur Aktualisierung von SendungenSendungsaktualisierung jederzeit möglich- also auch wenn die Sendung bereits in einer Tour in Ausführung ist (nicht empfohlen)Die Sendung kann nicht mehr aktualisiert werden, nach Tourzuordnung- stabiler Prozess zu Kosten von Flexibilität.Die Sendung kann nicht mehr aktualisiert werden, nach Tourfreigabe- Bei relevanten Änderungen an Abhol-/Zustellort, Datum oder Mengen/Volumen/Gewicht, kann ein Sendung aus einer bereits geplanten Tour “hinausfallen“. Dies sollte nur in Erwägung gezogen werden, wenn zwischen Sachbearbeiter des Verkaufsauftrags und Disponenten eine gute Kommunikation gewährleistet ist, da hier Änderungen die Planung des Disponenten durcheinander bringen kann
Regel zum Löschen von Aufträgenist das Gegenstück zu “Aktualisierung von Sendungen“Die Sendung kann nicht mehr gelöscht werden, nach Tourzuordnung..., nach Tourfreigabe..., nach Tourstart..., nach Beladebeginn- Abhängig vom internen Prozess des Kunden, wie mit spontanen Absagen/Verschiebungen umgegangen wird.
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 / Sendungs-ID eine wichtige Information, die ideallerweise im Vorsystem gemerkt wird.
Zusätzlich enthält die Response das Feld troughProcessType (nur lesend). Es gibt bei Mulden-Aufträgen den Prozesstyp an: 0 = Place, 1 = Empty, 2 = Change, 3 = Fetch. Bei Sendungen ohne Mulden-Auftrag ist der Wert null. Siehe auch Enums.
Beispiel-Requests
[
{
"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",
}
]Mittels RefId können bestehende Stammdaten referenziert werden. Mitgegebene Werte überschreiben die Stammdaten. Ist eine RefId nicht bereits erfasst wird diese temporär oder permanent (je nach Entität und Import-Einstellung) angelegt.
[
{
"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"
}
]Es können beliebig viele Produkte mitgegeben werden, falls das Produkt (mittels RefId) referenziert werden kann, werden die im X4fleet hinterlegten Stammdaten genommen. Spezifische Werte, wie zum Beispiel das Gesamtgewicht, können überschrieben werden. Falls das Produkt mit dieser RefId nicht existiert wird es temporär (oder mit entsprechender Importeinstellung permanent) angelegt.
[
{
"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"
}
]Beim verwenden von nicht vordefinierten Produkten kann auch der Produkttyp gesetzt werden. Für die verfügbaren Produkttypen siehe die Enum Liste.
Häufige Fehlermeldungen
- {"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}
--> Falsches Datum oder Datumsformat. Alle Datumsangaben müssen in UTC angegeben werden. - {"code":45,"messages":["Shipment has invalid pickup/dropoff dates. Shipment OrderNumber = XXX."],"RequestId":null,"Id":0}
--> Falsches Datum oder Datumsformat. Alle Datumsangaben müssen in UTC angegeben werden. - {"code":45,"messages":["Shipment has invalid date. Pickup date should be before dropoff date. Shipment OrderNumber = XXX."],"RequestId":null,"Id":0}
--> Abholdatum muss zwingend vor dem Zustelldatum liegen. - {"code":99,"messages":["There was an general error","Product unit Days is not available for containers."],"RequestId":null,"Id":0}
--> Wir haben verschiedene Produkttypen, und nicht alle Produkteinheiten sind für alle Produkttypen verfügbar (zB. Stunden sind nicht für Flüssigkeiten verfügbar). Prüfen Sie die betreffende Enum, ansonsten kontaktieren Sie unseren Support. - {"code":7,"messages":["Shipment cannot be inserted because there is already one","property: RefId='XXX', Source='XXX'"],"RequestId":null,"Id":0}
--> Duplikate sind auf dieser Gruppe ausgeschaltet, die Sendungs-RefID muss pro Quellsystem (source) eindeutig sein.