# API Dokumentation {% hint style="warning" %} Inhalt noch in Arbeit - Bei Fragen kontaktieren Sie bitte unseren [support](https://support.xplanis.com/support "mention") {% endhint %} ## Umgebungen * Produktion - PROD * Produktive Umgebung mit scharfen Daten * Web GUI: [https://www.x4fleet.com](https://www.x4fleet.com/) * Swagger UI: * Base URL Endpoints: [https://gateway.x4fleet.com](https://gateway.x4fleet.com/) * Staging - STAGING * Testumgebung für Konfiguration oder Anbindungen an X4fleet-API. Datenbank wird in unregelmässigen Abständen von PROD kopiert. Erhält während des laufenden Sprints noch unveröffentlichte Funktionen. * Web GUI: [https://staging.x4fleet.com](https://staging.x4fleet.com/) * Swagger UI: [https://gateway-staging.x4fleet.com/swagger/](https://gateway-staging.x4fleet.com/swagger/index.html) * Base URL Endpoints: [https://gateway-staging.x4fleet.com](https://gateway-staging.x4fleet.com/swagger/index.html) ## Authentifizierung Bevor die REST API von X4fleet benutzt werden kann, wird ein aktiver Benutzer mit der Rolle “Import Gateway“ benötigt. Folgend kann via Benutzername und Passwort ein Bearer Token beantragt werden. Dieser dient fortan als Token zur Authentifizierung weiterer Anfragen. Da dieser Token innert 90 Tagen abläuft, sollte dieser regelmässig erneuert werden. Im Rahmen von technischen Framework-Upgrades kann es dazu kommen, dass nach einem Release alle bisherigen Auth-Token invalidiert werden. Um nicht plötzlich keine Anfragen mehr senden zu können wird empfohlen, die Authentifizierung den eigentlichen Requests vorzulagern (und somit den Token wiederzuverwenden) und bei einem Fehlercode 401 - Unauthorized automatisch einen neuen Auth-Token zu lösen. Wichtig, bauen Sie eine re-try Limitation ein, um eine Endlosschleife zu verhindern. {% hint style="info" %} Endpoint: POST /token {% endhint %} ### Request {% code lineNumbers="true" %} ```json curl -X 'POST' \ 'https://gateway.x4fleet.com/token' \ -H 'accept: */*' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'Username=________&Password=________' ``` {% endcode %} \*aus Platzgründen wurde das Beispiel auf mehrere Zeilen verteil. cURL unterstützt keine Zeilenumbrüche! ### Response {% code lineNumbers="true" %} ```json { "access_token": "", "token_type": "bearer", "expires_in": , "accountId": "", "mainGroupId": "", "groupId": "", "role": "ImportUser", "firstName": "Max", "lastName": "Mustermann", "emailAddress": "max@mustermann.ch", "languageId": "1", "activated": "true", ".issued": "Fri, 28 Mar 2025 13:23:42 GMT", ".expires": "Thu, 26 Jun 2025 13:23:42 GMT" } ``` {% endcode %} Neben `access_token` werden später `accountId`(Account des Mandant/Kunden), `mainGroupId`(Hauptgruppe) und `groupId`(Subgruppe) erneut verwendet. ### Troubleshooting Wenn der “Import Gateway“-Benutzer nach fehlerhaften Anmeldeversuchen gesperrt wird, kann dieser via Admin erneut freigeschaltet werden. Dazu in X4fleet unter Einstellungen > Benutzer > “Import Gateway“-Benutzer an wählen > “Login freischalten“ drücken **Gängige Fehlermeldungen sind:** * {"error": "99" , "error\_description": "LoginLockedOut"} --> Account wurde aufgrund Fehlversuchen gesperrt * {"error": "99", "error\_description": "InvalidCredentials"} --> Falscher Benutzername oder Passwort * Error Code 415 - Unsupported Media --> es wird ein falscher Datentyp verwendet, zB. "application/json" anstatt "application/x-www-form-urlencoded" *** ## Shipment / Transportaufträge 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: 1. Wann soll wo etwas aufgeladen werden 2. Wann soll dieses etwas wo abgeladen werden 3. Welche Mengen, Volumen, Gewichte sollen transportiert werden 4. Gibt es bei Waren, Stellen und während des Transports etwas speziell zu beachten? {% hint style="info" %} Endpoint: POST /x4gateway/v1/import/shipment {% endhint %} ### Request - Übersicht {% code lineNumbers="true" %} ```json [ { "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) } ] ``` {% endcode %} Sendungsstatus * 0 - In Bearbeitung * 1 - Freigegeben * 2 - Verplant * 3 - Abholung abgeschlossen * 4 - Zustellung abgeschlossen * 5 - Mengensplitt * 7 - Wegsplitt * 8 - Abgeschlossen * 9 - Abgeschlossen mit Vorbehalt * 10 - Wieder geöffnet * 11 - Aufteilung des LKW-Ladungsprozesses FiscalStatus * 0 - Nicht definiert * 1 - In Bearbeitung * 2 - Angebot * 3 - Vorgesehen * 4 - Bestätigt * 5 - Aktualisiert * 6 - Gelöscht * 7 - Storniert * 8 - Erledigt * 9 - Unvollständig * 10 - Zur Verrechnung * 11 - Abrechnung in Bearbeitung * 12 - Verrechnet ### Request - Provider & Client 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. {% hint style="warning" %} Wenn immer möglich soll eine eindeutige `refId` vom Kundensystem mitgesendet werden. So können Dubletten minimiert und Datensätze mehrfach verwendet werden. {% endhint %} {% code lineNumbers="true" %} ```json "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 "contacts": [ { "id": 0, //vom System vergeben "refId": "string", //Refrenz zur Kontaktperson aus ERP "contactName": "string", "...": "...", //analog zum Geschäftspartner "isMainContact": true //dieser Kontakt wird per Standard als Ansprechperson angezeigt } ], "poBox": "string", //Postfach "fax": "string", "web": "string" } ``` {% endcode %} ### Request - Pickup & Dropoff Beschreibt den Ort an welchem Waren aufgeladen/abgeholt bzw. abgeladen/zugestellt werden. {% code lineNumbers="true" %} ```json "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 Pickup ``` {% endcode %} Art der Sendungsadresse (`kind`) * 1 - Leistungserbringungsort (LEO; meist Stelle des Geschäftspartners) * 2 - Depot/Terminal/Hub (meist eigene Stellen) * 3 - Fahrzeugstandort * 4 - Fahrzeugreinigung * 5 - Zoll * 6 - Treffpunkt * 6 - Technischer Stopp * 7 - Energie-Stopp (z.B. Ladesäule für Elektro-Fahrzeuge) * 8 - Sammelplatz 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) → nur `start` mitgeben * Es wird vorgegeben bis wann Waren abgeholt sein müssen (open start) → nur `end` mitgeben * 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, `start` und `end` müssen den selben Wert haben ### Request - Auftragsposition & Artikel {% code lineNumbers="true" %} ```json "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 "descriptionTranslation": {}, //Übersetzung Artikelbeschreibung DE, FR, IT, EN "notesTranslation": {}, //Übr. Art.Bemerkung DE, FR, IT, EN "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 } ] ``` {% endcode %} Alle möglichen 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 ### Einstellungen für Import von Transportaufträgen 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 Sendungen` * `Sendungsaktualisierung 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ägen` ist 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. *** ## Beispiel Request Bodies POST Shipment
POST Shipment, Minimalstruktur ohne Produkte ```json [ { "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.
POST Shipment, Minimalstruktur mit vordefinierten Produkten ```json [ { "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.
POST Shipment, Minimalstruktur mit neuem Produkt (Typ: Service) ```json [ { "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.
*** ## Tour Die Tour fast alle für die Erfüllung von N Sendungen notwendigen Informationen zusammen. Neben den Sendungen, sind das Informationen zum Fahrzeug/Anhänger, Fahrer, Zeitspanne und Ausführungsdatum, Stopps, Transportpunkte (inkl. Aufgaben für den Fahrer) sowie Checklisten und Vorkommnisse der ganzen Tour. Abhängig davon ob im Kundensystem Verkaufsaufträge mit einer Tour referenziert werden oder nicht; können Informationen zur Erfüllung der Sendungen auch einzeln von GET Shipment abgeholt werden. {% hint style="info" %} Endpoint: GET /x4gateway/v1/import/tour {% endhint %} *** ## Blob / Liefer- und Abholscheine Nach Abschluss einer Sendung kann der digitale Liefer-/Abholschein im PDF-Format via Schnittstelle abgeholt werden. Dazu muss zuerst von der jeweiligen Sendung die `reportUrl` aus dem Segment `./shipmentReports` (Ausgangspunkt ist bei GET Shipment `root` und bei GET Tour das jeweilige Shipment) abgeholt werden: {% code lineNumbers="true" %} ```json "shipmentReports": [ { "id": 0, "reportId": 0, "reportUrl": "string", "timeStamp": "2025-03-28T13:18:56.853Z", "reportType": 0 } ] ``` {% endcode %} Danach via Endpoint das Dokument anfragen. {% hint style="info" %} Endpoint: GET /x4gateway/v1/export/blob {% endhint %} *** ## Webhook Shipment & Tour Um Kundensysteme proaktiv über Änderungen an Transportaufträgen/Sendungen und Touren zu informieren, können in X4fleet für diese beiden Entitäten Webhooks konfiguriert werden. Je Entität gibt es eine Liste an Ereignissen, welche einen Webhook auslösen können. Webhooks können via Admin-Benutzer in X4fleet unter Einstellungen > Einstellungen > “Statusmeldungen (Webhooks)“ konfiguriert werden.
Für die Authentifizierung des POST-Requests kann entweder ein Paar aus Benutzername und Passwort oder ein x509-Zertifikat hinterlegt werden. Falls eine andere Methode benötigt wird oder X4fleet selber keine Requests an das Kundensystem senden soll, können diese auch proaktiv (z.B. im 5min Intervall) vom Kundensystem abgeholt werden. (Dazu die Checkbox `Nur Webhook Speicher verwenden` aktivieren) {% hint style="info" %} Endpoints für GET Shipment und Tour Webhook {% endhint %} Auch wenn der Payload sehr umfangreich ist, empfiehlt es sich den Webhook nur als Auslöser für “Hei, an Sendung X ist etwas passiert. Geh mal nachschauen!“ zu verstehen. Also das als Konsequenz ein GET Shipment oder GET Tour vom Kundensystem ausgelöst wird, um weitere Details zu erhalten. Dies da der Webhook-Payload langfristig schlanker werden soll und neue Datenstrukturen nur in den dazugehörigen Endpoints eingebaut werden. ### Auslöser Sendung/Transportauftrag * In Bearbeitung - Die Sendung wurde angelegt, ist aber noch in Bearbeitung bzw. es fehlen Informationen * Freigegeben - Die Sendung wurde manuell oder via Einstellung für die Planung auf eine Tour freigegeben * Verplant - Sendung wurde auf eine Tour geplant * Abholung abgeschlossen * Zustellung abgeschlossen * Mengensplitt - Sendung wurde auf N weitere Sendungen aufgeteilt, da die Menge nicht mit einer Fahrt erledigt werden kann * Wegsplitt - Sendung wurde auch N weitere Sendungen aufgeteilt, da die Waren über N Depots verschoben werden, bevor sie ihr Ziel erreichen * Abgeschlossen * Abgeschlossen mit Vorbehalt - Zwischen der Aufführung und der Planung gibt es Abweichungen (z.B. wurde weniger Geladen als geplant) * Wieder geöffnet - An der Sendung muss etwas korrigiert werden ### Auslöser Tour * In Planung - Der Tour wurde eine erste Sendung zugeteilt (meist nicht relevant für Kundensystem) * Geplant - Die Tour wurde berechnet bzw. optimiert (meist nicht relevant für Kundensystem) * Freigegeben - Die Tour wurde für die Ausführung freigegeben (je nach Prozess, können zwischen Freigabe und Ausführung einige Tage liegen) * Erneut Freigegeben - Die Tour wurde zurückgenommen, ggf. verändert und erneut zur Ausführung freigegeben * In Anpassung - Tour war mal freigegeben, wurde dann aber für eine Korrektur zurückgenommen * Überarbeitet - Nach “In Anpassung“ wenn erneut berechnet/optimiert * In Ausführung - Fahrer hat die freigegebene Tour gestartet * Komplett erledigt - Alle Transportpunkte und Sendungen gemäss Disposition erledigt * Unvollständig abgeschlossen - Abweichungen zwischen abgeschlossener Ausführung und Planung der Disposition * Nicht begonnen * Pausiert - z.B. bei Pause des Fahrers oder wenn am Vortag das Fahrzeug vorgeladen wurde und die Tour nun auf die weitere Ausführung wartet * \*(A) - Der Suffix heisst, dass die Tour mal im Status “In Ausführung“ war bevor sie in den neuen Status gewechselt hat * \*(P) - Der Suffix heisst, dass die Tour mal im Status “Pausiert“ war bevor sie in den neuen Status gewechselt hat *** ## Relevante Enum's ### Tourstatus ``` public enum TourStatusEnum { TourScheduled = 0, TourPlanning = 1, TourPlanned = 2, TourReleased = 3, TourReReleased = 4, TourInRevision = 5, TourRevised = 6, TourInExecution = 7, TourCompleteFinished = 8, TourIncompleteFinished = 9, Undefined = 10, TourPause = 11, TourInRevisionAfterExecution = 12, TourRevisedAfterExecution = 13, TourInRevisionAfterPause = 14, TourRevisedAfterPause = 15, TourInExecutionAfterUpdate = 16, TourCompleteFinishedAfterUpdate = 17, TourIncompleteFinishedAfterUpdate = 18, TourPauseAfterUpdate = 19, TourInRevisionAfterUpdate = 20, TourEmptyReleased = 21, //selten TourCommissioned = 22, //selten } ``` ### Sendungsstatus ``` public enum ShipmentStatusEnum { Editing = 5, Unallocated = 10, Allocated = 20, PickupCompleted = 70, DropoffCompleted = 110, QuantitySplit = 1000, //selten WaySplit = 1001, //selten Completed = 1002, //selten CompletedWithErrors = 1003, //selten Reopened = 1004, //selten TruckloadProcessSplit = 1005, //selten } ``` ### Fiskalstatus / Auftragsstatus Der Fiskalstatus ist ein vom Transport separater Status des Auftrags, primär angedacht um die Freigabe zu steuern. Über diesen Status kann zum Beispiel der Verkauf den Auftrag für die Planung bereits vorerfassen und erst nach Abschluss des Kaufvertrags die Freigabe des Auftrags für die effektive Auslieferung geben, sodass zB. die Tour freigegeben werden kann. ``` public enum OrderStatusEnum { Undefined = 0, InProcess = 1, Offer = 2, Intended = 3, Confirmed = 4, Updated = 5, Deleted = 6, Cancelled = 7, Completed = 8, Incompletely = 9, ReadyForBilling = 10, BillingInProgress = 11, Billed = 12 } ``` ### Sendungstyp Der Sendungstyp liefert zurück, um was für eine Sendung es sich handelt. ``` public enum ShipmentTypeEnum { InitialLeg = 0, // Abholung, Kunde zu Depot MainLeg = 1, // Hauptlauf, Depot zu Depot FinalLeg = 2, // Zustellung, Depot zu Kunde Direct = 3, // Direktverkehr, Kunde zu Kunde Undefined = 4 // Undefiniert, zB. keine Abhol-/Zustelladresse } ``` ### Auftrags- und Sendungsart Die Auftrags- und Sendungsart definiert, als was der Auftrag bzw. die Sendung im X4fleet interpretiert werden soll. Standardmässig wird 0 gesetzt, die anderen Werte sind nur relevant für Sie, wenn Sie im Rahmen des Projekts explizit darauf hingewiesen werden. ``` public enum ShipmentKindEnum { Shipment = 0, // normale Sendung Measurement = 1, // Wrapper für Gewichtsmessungen Flushing = 2, // Wrapper für Spülaufträge ProposalShipment = 3, // Wrapper für Offerten ExternalShipment = 4, // Wrapper für extern durchgeführte Sendungen } public enum OrderTypeEnum { TransportOrder = 0, // normaler Auftrag Order = 1, // Wrapper für Sammelaufträge Commercial = 2, // Wrapper für Offerten ExternalShipment = 3, // Wrapper für extern durchgeführte Aufträge } ``` ### Stellenart Die Stellenart definiert, als was für eine Stelle die Stelle im X4fleet definiert werden soll. In der Regel werden SPS (1) und Depot (2) verwendet. ``` public enum PoiKindEnum { ServiceProvisioningSite = 1, // Kunde Depot = 2, // Depot VehicleSite = 3, // Fahrzeugstandort VehicleCleaning = 4, // Fahrzeug Waschstation Customs = 5, // Zoll MeetingPlace = 6, // Treffpunkt TechnicalStop = 7, // Technischer Stop EnergyStop = 8, // Energiestop, Ladestation CollectionPlace = 9, // Sammelstelle } ``` ### Produkttyp Der Produkttyp definiert, um welchen Typ Produkt sich die Position handelt. ``` public enum ProductTypeEnum { Product = 1, // Stück- und Schüttgut Service = 2, // Dienstleistung Tool = 3, // Lademittel Container = 4, // Packstück, erlaubt die Verschachtelung von Produkten Franco = 5 // Franko-Position, ein Zusammenschluss aus Produkt und Dienstleistung, kommt vorwiegend bei der Kreislaufwirtschaft mit komplexen Abrechnungsverfahren zum Einsatz } ``` ### Produkteinheit Die Produkteinheit definiert, in welcher Einheit die Anzahl des Produktes zu werten ist. Nicht alle Einheiten sind für alle Produkttypen verfügbar. Über die Schnittstelle wird in der Regel nicht die Nummer, sondern der Name als RefID übermittelt (zB. "unit": "Ton"). ``` public enum ProductUnitEnum { EuroPalet = 1, EinwegPalet = 2, Halfpallet = 3, Gitterbox = 4, Colis = 5, Apparat = 6, Barrel = 7, Bundle = 8, Unit = 9, Kilo = 10, Ton = 11, CubicMeters = 12, Liter = 13, Hours = 14, Flat = 15, Bag = 16, BigBag = 17, Container = 18, Tin = 19, Bottle = 20, Carton = 21, Cassette = 22, Kettle = 23, RunningMeters = 24, Millimeter = 25, Minutes = 26, Pair = 27, Parcel = 28, Plate = 29, Poster = 30, SquareMeters = 31, Tube = 32, Coil = 33, Set = 34, Diverse = 35, Pole = 36, Packaging = 37, Kilometer = 38, LoadingMeters = 39, Meters = 40, Centimeters = 41, Bale = 42, Canister = 43, SquareCentimeters = 44, CubicCentimeter = 45, CubicDecimeters = 46, Gram = 47, Cartridge = 48, Ring = 49, Days = 50, P10 = 51, P20 = 52, P50 = 53, P100 = 54, Deciliter = 55, Pallet = 56, Rollbox = 57, CollectionContainer = 58, Kilometers = 59, Person = 60, Month = 61, } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://support.xplanis.com/api-dokumentation/api-dokumentation.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.