Lizenzbedingung

Einführung

Die PlantX API ist eine REST-Schnittstelle zum System Q Plant, über welche Mischgutbestellungen übermittelt und verwaltet werden können. Sie kann von jedem Client aufgerufen werden, der sich zuvor für den Zugriff registriert hat. Die Schnittstelle bietet auch einen Webhook, über den Clients – welche eine eigene API bereitstellen – proaktiv über bestimmte Ereignisse informiert werden.
Über die PlantX API können Sie folgende Aktivitäten durchführen:

Eine neue Mischgutbestellung aufgeben
Eine vorhandene Mischgutbestellung ändern oder löschen
Alle aktuellen Mischgutbestellungen abrufen

Abonnieren Sie zudem den Webhook. So übermittelt Q Plant folgende Information an Ihre eigene Schnittstelle:

Mischgutbestellung wurde vom Mischwerk angenommen/abgelehnt
Ein Lieferschein zur Bestellung wurde erstellt

Der PlantX Webhook ist ein Service, der bei Eintritt von einem der beiden oben genannten Ereignisse proaktiv als Client agiert, eine von Ihnen hinterlegte andere API aufruft und Ihnen die Daten zum Bestellstatus bzw. zum Lieferschein im JSON-Format übermittelt. Um den Webhook zu nutzen, müssen Sie selbst eine entsprechende REST-API betreiben und PlantX das Zugriffsrecht gewähren.

Die Aktivitäten der Schnittstelle werden im Folgenden inhaltlich beschrieben:

Mischgutbestellung aufgeben

Eine Mischgutbestellung ist ein konkreter Auftrag eines Bauunternehmens an eine Mischanlage zur Bereitstellung von Mischgut für ein Bauprojekt. Zu dieser Bestellung gehören Daten wie der bestellte Artikel, die Menge, Zeitpunkte und Takt der Lieferung usw. Wurde die Bestellung zuvor in einem anderen System als Q Plant erfasst – z.B. im Q Site des Bauunternehmens – so können ihre Daten anschliessend durch einen Aufruf der PlantX Schnittstelle an das Q Plant der Mischanlage übermittelt werden. Diese Übermittlung von Bestelldaten an den Auftragnehmer kann als eigentlicher Bestellvorgang betrachtet werden.

Mischgutbestellung ändern oder löschen

Eine zuvor übermittelte Bestellung entspricht zu einem späteren Zeitpunkt eventuell nicht mehr dem aktuellen Stand, z.B. weil Änderungen an der Menge oder der Lieferplanung beschlossen wurden oder weil die Bestellung storniert werden soll. Sofern eine Änderung gewünscht und vertraglich möglich ist, kann der Auftraggeber diese durch Aufruf der PlantX Schnittstelle veranlassen. Er übermittelt dabei den gleichen Datensatz wie bei der neuen Bestellung, verwendet jedoch die ID der bestehenden und überschreibt sie so mit den neu übermittelten Daten.

Aktuelle Mischgutbestellungen abrufen

Zu Kontroll- und Synchronisationszwecken kann es sinnvoll sein, sich über den aktuellen Stand der gelisteten Bestellungen aus Sicht der Mischanlage zu informieren. Die PlantX API stellt einen Endpunkt zur Verfügung, über den der Auftraggeber eine vollständige Liste aller seiner aktuellen Bestellungen anfordern kann, um den Informationsstand auf Seiten der Mischanlage zu kennen.

Status einer Bestellung erhalten

Hat die Mischanlage eine Bestellung erhalten, dann steht diese zunächst unter Vorbehalt. Die Anlage muss erst sicherstellen, dass der übermittelte Auftrag gemäss den Daten der Bestellung auch ausgeführt werden kann und die Kapazitäten dafür zur Verfügung stehen. Erst nach Bestätigung durch die Anlage ist der Auftrag angenommen. Später beginnt die Produktion des Mischguts, noch später die erste Verladung. Jeden dieser Fortschritte bei der Verarbeitung der Bestellung kann der Auftraggeber über die Schnittstelle erfahren, um den Fortgang in Echtzeit zu verfolgen.
Die Statusänderungen finden jedoch auf Seiten der Anlage statt. Sie können also nicht über die klassische API übermittelt werden, bei der Q Plant die Rolle des Servers einnimmt und erst dann kommunizieren kann, wenn ein Client sie anspricht. Stattdessen kommt hier ein Webhook zum Einsatz. Ihr System abonniert die Benachrichtigung von Events – in diesem Fall Statusänderungen – und hinterlegt die URL einer eigenen API, die Q Plant zur Übermittlung der Events aufrufen kann.

Lieferschein erhalten

Über die PlantX API können Lieferscheine, die bei Verladung jeder Fuhre des bestellten Mischguts ausgestellt werden, sofort zum Zeitpunkt der Ausstellung digital an den Auftraggeber übermittelt werden. Auch hier hinterlegt der Auftraggeber zunächst seine eigene API und abonniert die Lieferscheine. Q Plant reagiert danach auf die Ausstellung jedes Lieferscheins zur Bestellung und übermittelt ihn proaktiv an die API des Abonnenten.

Übersicht

Technische Informationen zur API
GET https://[RootUrl]/apiinfos	Liefert technische Informationen zur API
Geschäftsbeziehungen
POST https://[BaseUrl]/clientrelations	Legt eine neue Geschäftsbeziehung an
DELETE https://[BaseUrl]/clientrelations/{clientRelationId}	Löscht eine vorhandene Geschäftsbeziehung
HTTP-Subscriptions
POST https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions	Legt eine neue Subscription an
GET https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions/{httpSubscriptionId}	Gibt eine vorhandene Subscription zurück
GET https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions	Gibt alle vorhandenen Subscriptions zurück
DELETE https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions/{httpSubscriptionId}	Löscht eine Subscription
POST https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions/{httpSubscriptionId}/reactivate	Reaktiviert eine abgebrochene Subscription
Callback Methoden zu HTTP-Subscriptions
POST https://[CallbackURL-for-responseActions]	Rückmeldung zu einer Bestellung ("Akzeptiert", "mit Vorbehalt", oder "Abgelehnt")
POST https://[CallbackURL-for-deliveryNotes]	Weiterleitung eines Lieferscheins (strukturiert)
POST https://[CallbackURL-for-deliveryNoteDocuments]	Weiterleiten des Lieferschein-Dokuments (PDF)
POST https://[CallbackURL-for-vehicleStates]	Weiterleiten der aktuellen Positionen und Stati der Transportfahrzeuge
Mischgutbestellungen
PUT https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}	Aktualisiert die adressierte Bestellung oder legt diese an
GET https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}	Gibt eine vorhandene Bestellung zurück
Transportplanung
PUT https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/transportslots	Übermittelt eine neue oder aktualisierte Liste der Transportfahrten zur Bestellung
GET https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/transportslots	Fragt die Liste der Transportfahrten zur Bestellung ab
DELETE https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/transportslots	Löscht die gesamte Liste der Transportfahrten zu der Bestellung
Transportfahrzeuge
PUT https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles	Übermittelt eine neue oder aktualisierte Liste von Fahrzeugen zur Bestellung
GET https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles/	Fragt die Liste der Fahrzeuge ab
DELETE https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles/	Löscht die gesamte Liste der Fahrzeuge zur Bestellung
DELETE https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles/{registrationNumber}	Löscht ein einzelnes Fahrzeug
POST https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles/currentstates	Übermittelt eine Liste mit aktuellen Fahrzeug-Stati

URL's and Key

API Root URL [RootUrl]

Hierbei handelt es sich um die Basis-URL des PlantX API's der spezifischen Q Plant Kundeninstanz. Die einzelnen Kunden unterscheiden sich jeweils durch ihre Subdomain. Die von Ihnen benötigte Root URL erhalten Sie zusammen mit dem Access-Key vom Q Point Support.

Sie lautet beispielsweise: https://asphaltag-api.q-plant.com

API Base URL [BaseUrl]

Hierbei handelt es sich um die Basis-URL, welche zum eigentlichen Aufruf der einzelnen Methoden verwendet wird. Sie basiert auf der Root-URL und erweitert diese durch den Bezug zu einer bestimmten API-Version. Die von Ihnen benötigte Base URL erhalten Sie zusammen mit dem Access-Key vom Q Point Support.

Sie lautet beispielsweise: https://asphaltag-api.q-plant.com/v8/

API Key

Für den Zugriff auf die in dem Dokument angeführten Endpunkte des API ist ein API-Key mit der Key-Role "plantXOrderRole" notwendig.

Technische Informationen zur API

GET https://[RootUrl]/apiinfos

GET https://[RootUrl]/apiinfos

Eine GET-Abfrage auf die API Root-Url liefert technische Informationen zur API. Aktuell handelt es sich hierbei um eine Liste der unterstützten API-Versionen. Ein Server kann gleichzeitig mehrere unterschiedliche Versionen des API unterstützen. Client-Systeme können hiermit zur Laufzeit prüfen, ob der angesprochene Server die benötigte Version des API anbietet.

Response

200 - OK

Response Body

{ 
 "supportedApiVersions": [
    {
      "version": "v7",
      "isDeprecated": false
    },
	{
      "version": "v6",
      "isDeprecated": true
    }
  ]
 //... 
}

Response Body(supportedApiVersions)
version string(40) required	Einzelne vom Cluster bzw. Server unterstützten API Versionen (Bsp: "v2").
isDeprecated bool default: false	Die angegebene Version ist veraltet und wird in absehbarer Zeit nicht mehr unterstützt. Dieser Hinweis gibt abhängigen Systemen die Möglichkeit, dem Anwender einen entsprechenden Hinweis anzuzeigen und ihn darauf hinzuweisen, dass ein Update des Systems notwendig ist.

Geschäftsbeziehungen

Eine Geschäftsbeziehung ('clientRelation') bildet den Kontext von 'httpSubscriptions', mit denen der automatisierte Aufruf einer Drittschnittstelle für bestimmte Ereignisse in Q Plant angefordert werden kann.

Geschäftsbeziehung anlegen

POST https://[BaseUrl]/clientrelations

POST https://[BaseUrl]/clientrelations

Die Methode legt eine neue Geschäftsbeziehung beim Q Plant an. Nach erfolgreicher Registrierung liefert der Aufruf die `ìd` der Beziehung als Rückgabewert. Diese `ìd` muss vom Client-System zur Adressierung aller nachfolgenden Aufrufe gespeichert werden. Es handelt sich hierbei um eine Art Geheimnis. Deshalb bietet das API auch keine Möglichkeit, wie beispielsweise eine GET-Methode, um die `ìd` nachträglich abzufragen.

Request Body (clientRelations)
clientIdentifier string(100) required	Kennung des Client-Systems. Bei Q Site handelt es sich hierbei beispielsweise um den Workspace-Identifier.
clientName string(100)	Fakultative Bezeichnung des Client-Systems zur Anzeige im UI.
createdBy string(100)	Fakultative Angabe des Anwenders oder Services, welche die Relation angelegt hat.

Response

201 - Created Falls die Ressource neu angelegt wurde.

Response Body (clientRelations)
id UUID required	Global eindeutige und zwischen Client und Schnittstelle geheime 'id' der Geschäftsbeziehung. Wird von Q Plant festgelegt und beim Client gespeichert.
clientIdentifier string(100) required	Kennung des Client-Systems. Bei Q Site handelt es sich hierbei beispielsweise um den Workspace-Identifier.
clientName string(100)	Fakultative Bezeichnung des Clients-Systems zur Anzeige im UI.
createdBy string(100)	Fakultative Angabe des Anwenders oder Services, welche die Relation angelegt hat.

409 - Conflict Falls bereits eine Ressource mit der angegebenen ID existiert.

Einzelne Geschäftsbeziehung löschen

DELETE https://[BaseUrl]/clientrelations/{clientRelationId}

DELETE https://[BaseUrl]/clientrelations/{clientRelationId}

Die Methode entfernt die adressierte Geschäftsbeziehung. Mit dem Entfernen der Relation werden gleichzeitig auch sämtliche untergeordneten Subscriptions entfernt.

Path Params
clientRelationId UUID required	ID (UUID) der zu löschenden Geschäftsbeziehung.

Response:

200 - OK
404 - Not Found Falls keine Ressource mit der angegebenen ID existiert.

HTTP-Subscriptions

Eine 'httpSubscription' ist ein Abonnement von Callback-Aufrufen einer weiteren, aus Sicht von Q Plant externen Schnittstelle, die bei der Subscription hinterlegt wurde. Der Callback erfolgt immer dann, wenn in Q Plant das abonnierte Ereignis auftritt.
'httpSubscriptions' stehen immer im Kontext einer Geschäftsbeziehung ('clientRelation'). Deren eindeutige 'clientRelationId' ist bei jedem Aufruf des Endpunktes Teil der Basis-URL. Diese lautet also https://[BaseUrl]/clientrelations/{clientRelationId}/.

Subscription anlegen

POST https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions

POST https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions

Registriert einen Callback für eine bestimmte Ereignisart.

Request Body (httpSubscriptions)
subscribedEvent string(100) required	Abonnierte Ressource. Die Angabe entspricht einem Wert aus der folgenden Aufzählung: "weighingDeliveryNotes", "weighingDeliveryNotesPdf", "mixtureOrderResponseAction", “vehicleStates“. Siehe hierzu Abschnitt: "Callback-Methoden zu Http-Subscriptions".
callbackUrl string(1000) required	URL für den Callback.
authenticationType string(40) required	Angewendete Authentifizierungmethode. Es stehen die Varianten "basic", "apikey", "activedirectory", “none” zur Auswahl.
basicAuthUsername string(100) conditionally required	Benutzername zur Authentifizierung des Callbacks. Pflichtfeld, falls im Feld "authenticationType" der Wert "basic" gewählt wurde.
basicAuthPassword string(100) conditionally required	Passwort zur Authentifizierung des Callbacks. Pflichtfeld, falls im Feld "authenticationType" der Wert "basic" gewählt wurde.
httpAuthHeaderKey string(100) conditionally required	Header Key für API Key Authentifizierung z.B. Authentication. Pflichtfeld, falls im Feld "authenticationType" der Wert "apikey" gewählt wurde.
httpAuthHeaderValue string(4000) conditionally required	Header Value (enthält den API Key) z.B. ApiKey ((xxxx-API-KEY-xxxx)). Pflichtfeld, falls im Feld "authenticationType" der Wert "apikey" gewählt wurde.

Response

201 - Created Falls die Ressource neu angelegt wurde.

Response Body (Invoices)
id UUID required	Die von Q Plant festgelegte, eindeutige ID (UUID) der Subscription.
...	Restliche Felder gemäss Request Body. Die Werte werden so zurückgegeben, wie sie in Q Plant aktuell gespeichert sind.

Einzelne Subscription abrufen

GET https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions/{httpSubscriptionId}

GET https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions/{httpSubscriptionId}

Gibt eine einzelne Subscription mitsamt deren Daten und Status zurück.

Path Params
httpSubscriptionId UUID required	Id der angeforderten Subscription.

Response

200 - OK

Response Body (httpsubscriptions)
state string(50) required	Aktueller Status der Subscription. Hierbei handelt es sich um einen Aufzählungstyp ("active", "failed", "aborted").
subscribedEvent string(100) required	Abonnierte Ressource. Die Angabe entspricht einem Wert aus der folgenden Aufzählung: "weighingDeliveryNotes", "weighingDeliveryNotesPdf", "mixtureOrderResponseAction".
callbackUrl string(1000) required	URL für den Callback.
authenticationType string(40) required	Angewendete Authentifizierungmethode. Es stehen die Varianten "basic", "apiKey" zur Auswahl.
failureCause string(1000)	Hinweise zur Ursache eines allfälligen Fehlers oder des Abbruchs.
abortedDt datetime	Zeitpunkt zu welchem die Subscription abgebrochen wurde.

404 - Not Found Falls die adressierte Ressource nicht existiert.

Alle Subscriptions der Client-Relation abrufen

GET https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions

GET https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions

Gibt eine Liste von Subscriptions zurück, jede mitsamt Daten und Status.

Response

200 - OK

Response Body (httpsubscriptions)
id uuid required	Systemübergreifend eindeutige ID (GUID) der Subscription. Diese wird von Q Plant beim Anlegen festgelegt und an den Aufrufer zurückgeliefert.
state string(50) required	Aktueller Status der Subscription. Hierbei handelt es sich um einen Aufzählungstyp ("active", "failed", "aborted").
subscribedEvent string(100) required	Abonnierte Ressource. Die Angabe entspricht einem Wert aus der folgenden Aufzählung: "weighingDeliveryNotes", "weighingDeliveryNotesPdf", "mixtureOrderResponseAction".
callbackUrl string(1000) required	URL für den Callback.
authenticationType string(40) required	Angewendete Authentifizierungsmethode. Es stehen die Varianten "basic", "apiKey" zur Auswahl.
failureCause string(1000)	Hinweise zur Ursache eines allfälligen Fehlers oder des Abbruchs.
abortedDt datetime	Zeitpunkt, zu welchem die Subscription abgebrochen wurde.

Subscription löschen

DELETE https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions/{httpSubscriptionId}

DELETE https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions/{httpSubscriptionId}

Löscht die adressierte Subscription mit der angegebenen ID.

Path Params
httpSubscriptionId UUID required	ID (UUID) der zu löschenden Subscription.

Response

200 - OK
404 - Not Found Falls keine Ressource mit der angegebenen ID existiert.

Abgebrochene Subscription reaktivieren

POST https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions/{httpSubscriptionId}/reactivate

POST https://[BaseUrl]/clientrelations/{clientRelationId}/httpsubscriptions/{httpSubscriptionId}/reactivate

Wurde eine Subscription aufgrund eines dauerhaften Fehlers abgebrochen (Status "aborted"), so wird sie beim Aufruf dieser Methode wieder zurück in den Status "active" gesetzt und überträgt weiterhin Ereignisse.

Response

200 - OK
404 - Not Found Falls keine Ressource mit der angegebenen ID nicht existiert.

Callback-Methoden zu Http-Subscriptions

Die nachfolgenden Endpunkte müssen vom Clientsystem, welches eine Subscription einträgt, bereitgestellt werden. Sie werden von Q Plant aufgerufen, sobald das entsprechende Ereignis eintritt.

Rückmeldung zu Mischgutbestellung

POST https://[CallbackURL-for-responseActions]

POST https://[CallbackURL-for-responseActions]

Drittsysteme, welche eine Subscription für den Event "mixtureOrderResponseAction" registrieren, müssen einen solchen Endpunkt bereitstellen. Die Callback-Methode wird aufgerufen, sobald die Mischanlage eine Rückmeldung zu einer Mischgutbestellung ("Akzeptiert", "mit Vorbehalt", oder "Abgelehnt") abgibt.

Request Body (responseActions)
mixtureOrderId UUID required	ID der Mischgutbestellung, auf welche sich die Rückmeldung bezieht.
action string(40) required	Rückmeldung bzw. Action-Kennung (Enum: 'declined', 'accepted', 'tentative').
message string(1000)	Auf die jeweilige Rückmeldung bezogene Textnachricht. Beispielsweise bei 'tentative' ein Hinweis auf den Vorbehalt - oder bei 'declined' der Grund für die Ablehnung.
refersToRevision integer required must be greater than 0	Revisionsstand der Mischgutbestellung, auf den sich die Rückmeldung bezieht.
responseDt datetime required	Zeitpunkt (UTC), zu welchem die Action vom Anwender ausgelöst wurde. Mithilfe dieses Zeitstempels wird sichergestellt, dass jeweils die zeitlich letzte ausgelöste Aktion auf der Empfängerseite ausgeführt wird. Dieser Zeitwert ist zwingend mit einem UTC-Bezug anzugeben!

Response

Der Webhook erwartet von der API des Abonnenten eine der folgenden Antworten:

200 OK oder 201 Created Wenn der Befehl entgegengenommen wurde.

Der Erhalt einer anderen Response wird von der httpsubscription als Fehler interpretiert, der zur Wiederholung der Anfrage oder zur vorübergehenden Unterbrechung des Service führen kann.

Weiterleiten eines Lieferscheins

POST https://[CallbackURL-for-deliveryNotes]

POST https://[CallbackURL-for-deliveryNotes]

Drittsysteme, welche eine Subscription für den Event "weighingDeliveryNotes" registrieren, müssen einen solchen Endpunkt bereitstellen. Die Callback-Methode wird aufgerufen, sobald die Mischanlage zu einer Mischgutbestellung der zugrundeliegenden Client-Relation einen neuen Lieferschein ausgibt. Im Allgemeinen ist dies der Zeitpunkt der Bruttowiegung des Transportfahrzeugs.

Request Body (weighingDeliveryNotes)
id UUID	GUID des Lieferscheins. Dieser wird entweder vom System mitgeliefert, welches den Lieferschein erzeugt oder ansonsten von Q Site beim erstmaligen Speichern festgelegt.
docketNumber string(200) required	Lieferscheinnummer. Sowohl der Wert als auch die Formatierung der Nummer wird durch dasjenige System bestimmt, welches den Lieferschein ausgibt. In der Regel handelt es sich hierbei um das Wiegesystem der Mischanlage.
issueDt datetime required	Zeitpunkt, zu welchem der Lieferschein erzeugt wurde. In der Regel entspricht dies dem Zeitpunkt der Bruttowiegung auf der Mischanlage. Dies wiederum kann mit einem geringen zeitlichen Verzug als Abfahrtszeitpunkt des LKW's angenommen werden. Dieser Zeitpunkt wird durch die Mischanlage bzw. durch dasjenige System bestimmt, welches den Lieferschein ausgibt.
accountingCompanyIdentifier string(100)	Eindeutige Kennung (Unternehmens-ID oder Umsatzsteuer-Nummer) des Unternehmens, welche das Mischgut liefert und anschliessend auch in Rechnung stellt.
accountingCompanyName string(100)	Name der Firma, welche das Mischgut liefert und anschliessend auch in Rechnung stellt
accountingCompanyPostalAdress string(1000)	Zusammenhängender Informations-String mit der kompletten Postanschrift des Unternehmens, welche das Mischgut liefert.
cancelled bool default: false	Der Lieferschein ist storniert und wird deshalb nicht verrechnet
deliveryTerm string(40) required	Lieferkonditionen nach "International Commercial Terms". Zulässig sind: 'EXW': Ex Works bzw. Ab Werk 'DAP': Delivered at Place bzw. Frei Baustelle
goodsDirection string(40)	Warenflussrichtung (Enum) aus Sicht der ausstellenden Instanz. "outgoing" (Ware bzw. Material wurde an den Kunden abgegeben), "incoming" (Ware bzw. Material wurde vom Kunden entgegengenommen). Fehlt die Angabe, wird per Definition outgoing gesetzt.
articleIdentifier string(100) required	Artikelnummer des gelieferten Mischguts.
articleName string(100)	Artikelbezeichnung des gelieferten Mischguts
initialInspectionIdentifier string(100)	Kennung der Erstprüfung des gelieferten Mischguts (in der Regel eine Nummer).
declarationOfPerformanceIdentifier string(100)	Kennung der Leistungserklärung des gelieferten Mischguts.
tareWeight decimal(10,3) must be greater than 0	Taragewicht in der Masseinheit 'tareUnit'.
tareIdentifier string(100)	Signatur des Wiegevorgangs bei eichamtlich abgenommenen Wiegesystemen. Die Signatur bildet die Referenz zum eichamtlichen Speicher und wird zur Rückverfolgung des Wiegevorgangs herangezogen.
tareIsManual bool default: false	Das Taragewicht wurde nicht gemessen, sondern manuell durch den Anwender erfasst.
tareExecutionDt datetime conditionally required	Ausführungszeitpunkt der Tara-Wiegung. Pflichtfeld, falls der Wert 'tareWeight' vorhanden ist.
tareUnit string(40) conditionally required	Masseinheit des Tara-Gewichtswerts. Pflichtfeld, falls der Wert 'tareWeight' vorhanden ist.
grossWeight decimal(10,3) must be greater than 0	Bruttogewicht in der Masseinheit 'grossUnit'.
grossIdentifier string(100)	Signatur des Wiegevorgangs bei eichamtlich abgenommenen Wiegesystemen. Die Signatur bildet die Referenz zum eichamtlichen Speicher und wird zur Rückverfolgung des Wiegevorgangs herangezogen.
grossIsManual bool default: false	Das Bruttogewicht wurde nicht gemessen, sondern manuell durch den Anwender erfasst.
grossExecutionDt datetime conditionally required	Ausführungszeitpunkt der Brutto-Wiegung. Pflichtfeld, falls der Wert 'grossWeight' vorhanden ist.
grossUnit string(40) conditionally required	Masseinheit des Brutto-Gewichtswerts. Pflichtfeld, falls der Wert 'grossWeight' vorhanden ist.
quantity decimal(10,3) required must be greater than 0	Liefermenge des spezifizierten Artikels.
quantityUnit string(40) required	Masseinheit der Mengenangabe.
vehicleRegistrationNumber string(100) required	Amtliches Kennzeichen des Transport LKW's bzw. des Zugfahrzeugs.
vehicleRegistrationNumberTrailer string(100)	Amtliches Kennzeichen des Aufliegers.
vehicleTypeName string(100)	Bezeichnung des eingesetzten Fahrzeugtyps.
carrierIdentifier string(100)	Kennung der Speditionsfirma.
loadingTemperature integer must be greater than 0	Mischguttemperatur bei Verladung auf den LKW (Ganzzahl).
temperatureUnit string(40) conditionally required	Masseinheit aller Temperaturangaben im Lieferschein. Pflichtfeld, falls 'loadingTemperature' vorhanden. Zulässige Werte sind '°C' und 'F'.
orderId UUID conditionally required	ID der zugrundeliegenden Bestellung. Diese Kennung stammt vom Auftraggeber und wird im Rahmen des Bestellvorgangs an die Mischanlage übermittelt. Die Mischanlage fügt diese Information anschliessend unverändert dem Lieferschein-Datensatz hinzu. Sie dient auf Seite des Auftraggebers bzw. Empfängers des Lieferscheins zur Referenzierung und Zuordnung zur Bestellung. Pflichtfeld, falls das Feld 'orderIdentifier' (siehe unten) leer ist.
orderIdentifier string(100) conditionally required	Kennung der zugrundeliegenden Bestellung. Diese Kennung stammt vom Auftraggeber und ist für diesen eindeutig. Sie wird im Rahmen des Bestellvorgangs an die Mischanlage übermittelt. Die Mischanlage fügt diese Information anschliessend unverändert dem Lieferschein-Datensatz und dem QR-Code hinzu. Sie dient auf Seite des Bestellers bzw. Empfängers des Lieferscheins zur Referenzierung und Zuordnung zur Bestellung. Pflichtfeld, falls das Feld 'orderID' (siehe oben) leer ist.
projectIdentifier string(100)	Kennung der Baustelle bzw. des Projektes. Diese Kennung stammt vom Auftraggeber und wird im Rahmen des Bestellvorgangs an die Mischanlage übermittelt. Die Mischanlage fügt diese Information anschliessend unverändert dem Lieferschein-Datensatz und dem QR-Code hinzu. Sie dient auf Seite des Bestellers bzw. Empfängers des Lieferscheins zur Referenzierung und Zuordnung zum Projekt bzw. der Baustelle.
plantIDDirectories UUID conditionally required	ID (GUID) der liefernden Mischanlage aus Q Directories. Falls die Mischanlage in Q Directories registriert ist, kann der Lieferant die ID als Referenz innerhalb des Lieferscheindatensatzes mitliefern. Pflichtfeld, falls das Feld 'plantIdentifier' (siehe unten) leer ist.
plantIdentifier string(100) conditionally required	Eindeutiger Identifier bzw. Bezeichnung der liefernden Mischanlage. Pflichtfeld, falls das Feld 'plantIDDirectories' (siehe oben) leer ist.
supplierCustomerIdentifier string(100) required	Kennung des auf dem Lieferschein aufgeführten Kunden. In der Regel handelt es sich hierbei um die Kunden-Nummer aus dem ERP des Mischgutlieferanten.
customerPostalAddress string(1000)	Zusammenhängender Informations-String mit der kompletten Postanschrift des Kunden.
supplierSiteIdentifier string(100)	Kennung der Baustelle, an welche das Mischgut geliefert wurde. Hierbei handelt es sich um die Baustellen-Nummer aus dem ERP des Mischgutlieferanten.
sitePostalAddress string(1000)	Zusammenhängender Informations-String mit der kompletten Postanschrift der Baustelle.
annotation string(1000)	Allfällige Hinweise oder Anmerkungen des Lieferanten zur Lieferung.
estimatedTimeOfDepartureDt datetime	Geschätzter Abfahrtszeitpunkt des Transportfahrzeugs im Mischwerk (ETD).
estimatedTimeOfArrivalDt datetime	Geschätzter Ankunftszeitpunkt des Transportfahrzeugs auf der Baustelle (ETA).

Response

Der Webhook erwartet von der API des Abonnenten eine der folgenden Antworten:

200 OK oder 201 Created Wenn der Lieferschein entgegengenommen wurde.
Weitere Infos zu den Response Codes finden sich unter: REST Grundlagen zu Q Exchange, Abschnitt: Callback Subscriptions, Fehlerbehandlung und Status.

Weiterleiten eines PDF-Lieferscheins

POST https://[CallbackURL-for-deliveryNoteDocuments]

POST https://[CallbackURL-for-deliveryNoteDocuments]

Drittsysteme, welche eine Subscription für den Event "weighingDeliveryNotesPdf" registrieren, müssen einen solchen Endpunkt bereitstellen. Die Callback-Methode wird aufgerufen, sobald das Mischwerk zu einem bestehenden Lieferschein-Datensatz der zugrundeliegenden Client-Relation ein PDF-Dokument ausgibt. Im Gegensatz zu den restlichen Endpunkten handelt es sich hierbei um einen multipart/formdata Request mit zwei unterschiedlichen Parts.

Zu einem bestimmten Lieferschein (deliveryNotesId) lassen sich nacheinander mehrere unterschiedliche Revisionsstände des Dokuments übermitteln. Dabei gilt der Grundsatz, dass die im Dokument aufgeführten Angaben zu jedem Zeitpunkt mit den Informationen im strukturierten Datensatz übereinstimmen. Das Dokument darf lediglich durch Hinzufügen von Informationen, wie beispielsweise einer Unterschrift oder zusätzlichen Angaben zu Abladezeitpunkte oder Wartezeiten, vervollständigt werden.

Die Lieferschein-ID wird dem empfangenden System durch einen Pfad-Parameter mitgegeben.

Header Params
Content-Type: required	multipart/form-data

Request Body (Part: Lieferschein-ID)
Key “name” required	“deliveryNoteId”
ContentType required	"text/plain"
Value required	Systemübergreifende eindeutige ID (UUID) des Lieferscheins (beispielsweise: d1b68673-ea86-4ba4-a689-a3959fb8b0cb).

Request Body (Part: Lieferschein-Dokument)
Key “name” required	“deliveryNote”
ContentType required	MIME Type des Dokuments. Momentan ist lediglich "application/pdf" zulässig.
Value required	[file in binary data]

Response

Der Webhook erwartet von der API des Abonnenten eine der folgenden Antworten:
- 200 OK oder 201 Created Wenn das Lieferschein-Dokument entgegengenommen wurde.
- Weitere Infos zu den Response Codes finden sich unter: REST Grundlagen zu Q Exchange, Abschnitt: Callback Subscriptions, Fehlerbehandlung und Status

Weiterleiten der aktuellen Positionen und Stati der Transportfahrzeuge

POST https://[CallbackURL-for-VehicleStates]

POST https://[CallbackURL-for-VehicleStates]

Drittsysteme, welche eine Subscription für den Event "vehicleStates" registrieren, müssen einen solchen Endpunkt bereitstellen. Mithilfe dieser Subscription erhalten Bestellsystem der Baufirmen fortlaufend Statusinformationen inkl. der momentanen Geo-Position zu den eingesetzten Transportfahrzeugen. Hierbei handelt es sich um diejenigen Fahrzeug, welche im Auftrag des Mischgutlieferanten, d.h. mit einer Lieferkondition “Frei Baustelle” ('DAP': Delivered at Place), für eine Mischgutbestellung der Baufirma (Client Relation) eingesetzt werden.

Die Callback-Methode wird unmittelbar nach einer Statusänderung oder aber einer massgeblichen Positionsänderung aufgerufen. Auf Seite von Q Plant findet lediglich ein bedingtes Queueing statt. Nach einem allfälligen Verbindungsunterbruch erhält der Empfänger deshalb jeweils lediglich die zeitliche letzte Statusinformation übermittelt.

Der Fahrzeugstatus wird in einem bestimmten Mindest-Intervall (in der Regel 10min) an den Empfänger übermittelt. Ist die Positionsinformation älter als 15 min, muss davon ausgegangen, dass das Fahrzeug nicht mehr für die vorangehende Bestellung fährt.

Request Body (currentStates)
orderId UUID required	ID der Mischgutbestellung, für welches das Fahrzeug momentan unterwegs ist. Diese ID stammt vom Auftraggeber und wird im Rahmen des Bestellvorgangs an die Mischanlage übermittelt.
vehicleRegistrationNumber string(100) required	Amtliches Kennzeichen des Transport LKW's bzw. des Zugfahrzeugs.
currentGeoPosition geoPoint required	Momentane Fahrzeug-Geo Position.
currentGeoPositionDt datetime required	Zeitpunkt, zu welchem sich das Fahrzeug an dieser Position befand. Der Zeitpunkt wird durch das Device bestimmt, welches auch die Geoposition ermittelt. Eine Zeitsynchronisation lasst sich nicht in jedem Fall sicherstellen, weshalb die Möglichkeit von zeitlichen Abweichungen besteht.
deliveryNoteId uuid	Lieferschein-ID, falls das Fahrzeug aktuell beladen ist. Entfällt, solange das Fahrzeug leer unterwegs ist oder die ID nicht bekannt ist.
docketNumber string(200)	Lieferscheinnummer, falls das Fahrzeug aktuell beladen ist. Entfällt, solange das Fahrzeug leer unterwegs ist.
estimatedRemainingDriveDuration int must be greater or equal than 0	Geschätzte restliche Fahrdauer bis zur Zieldestination in 's'. Der Wert bezieht sich auf die momentane Geoposition 'currentGeoPosition’ sowie den Zeitpunkt ‘currentGeoPositionDt’. Der geschätzte Ankunftszeitpunkt ETA ergibt sich anschliessend, indem die Dauer zum Aufzeichnungszeitpunkt hinzuaddiert wird.
estimatedTimeOfArrivalDt datetime	Geschätzte Ankunftszeitpunkt “estimated time of arrival” des Fahrzeugs an der Zieldestination. Der Zeitpunkt wird aufgrund der Fahrzeugposition fortlaufend neu bestimmt.
isLoaded bool	true: Das Fahrzeug ist momentan beladen. false oder NULL: Das Fahrzeug ist momentan nicht beladen.
isPaused bool	true: Das Fahrzeug bzw. der Fahrer absolviert aktuell eine Ruhepause.

Request Body

[
  {
		"orderId": "49d06644-d13e-4f69-87b7-14a5adb80f20",
		"orderIdentifier": "2205-1015-1704",
		"vehicleRegistrationNumber": "KB-EG-2345",
		"currentGeoPosition": "47.496860;8.343697",
		"currentGeoPositionDt": "2019-01-06T06:10:00",
		"docketNumber": "2378736",
		"estimatedRemainingDriveDuration": "1578",
		"isLoaded": true,
		"isPaused": false
	},
	{
        "orderId": "49d06644-d13e-4f69-87b7-14a5adb80f20",
		"orderIdentifier": "2205-1015-1704",
		"vehicleRegistrationNumber": "KB-AB-6789",
		"currentGeoPosition": "47.494325;8.340000",
		"currentGeoPositionDt": "2019-01-06T06:05:00",
	}
]

Response

201 - Created Falls die Positionsliste entgegengenommen wurde.
Weitere Infos zu den Response Codes finden sich unter: REST Grundlagen zu Q Exchange, Abschnitt: Callback Subscriptions, Fehlerbehandlung und Status

Mischgutbestellungen

Mischgutbestellungen bzw. MixtureOrders sind konkrete Aufträge eines Bauunternehmens an eine Mischanlage zur Bereitstellung von Mischgut für ein Bauprojekt. Zu dieser Bestellung gehören Daten wie der bestellte Artikel, die Menge, Zeitpunkte und Takt der Lieferung, usw.

Mischgutbestellung übermitteln oder ersetzen

PUT https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}

PUT https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}

Mit dem PUT-Aufruf des Endpunktes /mixtureOrders wird eine Bestellung mit den neu übergebenen Daten aktualisiert, falls sie vorher schon existiert hat. Hat sie nicht existiert, dann wird sie neu angelegt. Der Aufruf muss immer eine eindeutige Identifikationsnummer der Bestellung, die mixtureOrderId enthalten. Ausserdem muss im Request Body ein Datensatz gemäss unten beschriebener Struktur übergeben werden, der mindestens alle Pflichtfelder (*required) enthält.

Path Params
mixtureOrderId UUID required	Systemübergreifende eindeutige ID (UUID) der Mischgutbestellung. Diese wird vom System des Auftraggebers festgelegt.

Request Body (mixtureOrders)
identifier string(100) required	Systemübergreifende Kennung der Bestellung. Diese wird an die Mischanlage übermittelt und anschliessend unverändert auf die Lieferscheine bzw. im QR-Code aufgedruckt oder dem Lieferschein-Datensatz mitgeführt. Auf der Baustelle dient diese Kennung anschliessend als Referenz, um den Lieferschein wieder der Bestellung zuzuordnen. Der Identifier wird vom System des Bestellers festgelegt und sollte eindeutig sein. Für die Mischanlage ist dieser Wert nicht von Bedeutung und deshalb readonly.
contractIdentifier string(100)	Kennung des Rahmenvertrags unter den diese Mischgutbestellung fällt. Der Rahmenvertrag wird zwischen Mischgutlieferant und Baufirma abgeschlossen. Er regelt die für das gesamte Bauvorhaben zu liefernden Mischgutartikel inkl. Abnahmemengen, sowie den vereinbarten Preis.
plantIDDirectories UUID conditionally required	ID (GUID) der liefernden Mischanlage aus Q Directories. Falls die Mischanlage in Q Directories registriert ist, kann der Besteller dies zur Referenzierung verwenden. Pflichtfeld, falls das Feld 'plantIdentifier' leer ist.
plantIdentifier string(100) conditionally required	Eindeutiger Identifier bzw. Bezeichnung der liefernden Mischanlage. Pflichtfeld, falls das Feld 'plantIDDirectories' leer ist. Referenziert (nur) in diesem Fall die Mischanlage.
goodsDirection string(40)	Warenflussrichtung aus Sicht des Empfängers der Bestellung. "outgoing" (Ware bzw. Material wird an den Kunden abgegeben bzw. geliefert), "incoming" (Ware bzw. Material wird vom Werk entgegengenommen bzw. angeliefert). Fehlt die Angabe, wird per Definition outgoing gesetzt.
deliveryTerm string(40) required	Lieferkonditionen nach "International Commercial Terms". Fehlt die Angabe, wird per Definition (EXW) "Ab Werk" gesetzt. Zulässig sind: 'EXW': Ex Works bzw. Ab Werk 'DAP': Delivered at Place bzw. Frei Baustelle
articles list[article] required	Liste der bestellten Mischgutartikel inkl. Menge und Angabe ihrer Lieferreihenfolge. Die Liste muss mindestens einen Eintrag enthalten.
deliveryPerformance decimal(10,3) must be greater than 0	Für den Einbau benötigte Lieferleistung.
performanceUnit string(40) conditionally required	Masseinheit aller Leistungsangaben in der Bestellung. In der Regel [t/h]. Pflichtfeld, falls Wert 'deliveryPerformance' vorhanden ist.
roundTripDuration integer must be greater than 0	Geschätzte Umlaufdauer der Transportfahrzeuge [min]. Dies ist die Summe aus der Beladedauer auf dem Mischwerk, der Fahrzeit zur Baustelle, der Warte- und Entladedauer auf der Baustelle sowie der Rückfahrt zum Mischwerk.
expectedDeliveryEndDt datetime	Zeitpunkt, zu welchem voraussichtlich die letzte Lieferung auf der Baustelle ankommt.
countOfVehicles integer must be greater than 0	Geplante Anzahl der eingesetzten Transportfahrzeuge. Diese Angabe entfällt, wenn stattdessen eine detaillierte Transportliste "transports[ ]" mitgegeben wird.
loadingCapacity decimal(10,3) must be greater than 0	Ladekapazität der eingesetzten Transportfahrzeuge [t]. Diese Angabe entfällt, wenn stattdessen eine detaillierte Transportliste "transports[ ]" mitgegeben wird.
transports list[transport]	Optionale Liste der Transporte. Die Liste beschreibt in der Regel die ersten Transportfahrten der eingesetzten LKWs und damit nur ein Teil des gesamten Transportplans. Wird eine Transportliste angeführt, entfallen stattdessen die allgemeinen Angaben zum Transport bzw. die Felder "deliveryTerm", "countOfVehicles" sowie "loadingCapacity".
hasTransportslots bool default: false	Die Bestellung verfügt über einen getrennten Transportplan. Hierbei handelt es sich um eine Liste aufeinanderfolgender und zeitlich geplanter Transportfahrten. Der Plan wird über einen gesonderten Endpunkt, in Form der Entität transportslots übermittelt. Siehe hierzu: Abschnitt "Transportplanung", PUT tranportslots. Das Flag muss mit der ersten Übermittlung der Bestellung korrekt gesetzt werden und darf daraufhin nicht mehr verändert werden! Entsprechende Versuche werden mit dem Fehlercode "409 Conflict" beantwortet. Im Falle einer "dynamischen Transportplanung", wird die Liste während der Ausführung des Transports zyklisch durch das Bestellsystem aktualisiert und an die momentane Ausgangssituation angepasst.
annotation string(1000)	Fakultative Anmerkungen oder Hinweise zur Bestellung vom Auftraggeber an den Mischgutlieferanten.
ordererName string(100)	Name des Auftraggebers.
ordererCompanyName string(100) required	Name der beauftragenden Firma, welche schlussendlich die Lieferung vom Mischgutlieferanten verrechnen wird.
ordererCompanyIdentifier string(100)	Eindeutige Firmenkennung der beauftragenden Firma (Unternehmens-ID oder Umsatzsteuer-Nummer).
ordererPostalAddress string(1000)	Zusammenhängender Informations-String mit der kompletten Postanschrift des Auftraggebers (Rechnungsanschrift).
siteIdentifier string(100) required	Eindeutige Kennung der Baustelle, an welche das Mischgut geliefert wird. Hierbei handelt es sich um die Baustellen- oder Projekt-Kennung aus dem System des Auftraggebers.
siteName string(100)	Name der Baustelle.
siteCostCenter string(100)	Kostenstelle der Baustelle auf Seite des Bestellers. In der Regel handelt es sich hierbei um die Kostenstelle des zugeordneten Bauleiters.
sitePostalAddress string(1000)	Zusammenhängender Informations-String mit der kompletten Postanschrift der Baustelle.
siteGeoPosition list[geopoint]	Liste von geoPoint-Objekten, welche jeweils die Geo-Position bzw. die Koordinaten von Anfang und Ende der Baustelle umfassen.
siteArea geofence	Optionale Angabe des Geofence um das Baustellengelände. Das Geofence wird in Form eines Polygons im Geo-JSON-Format geliefert. Es handelt sich um einen linearen Ring d.h. eine Aufzählung der Polygon-Eckpunkte (longitude, latitude WGS 84 ) im Gegenuhrzeigersinn. Der letzte Punkt ist mit dem Ersten deckungsgleich, womit das Polygon vollständig geschlossen ist. Beispiel: `{"type": "Polygon","coordinates":[[ [9.5606433, 49.1774781],[9.5606482, 49.1774756],[9.5606496, 49.1774767],[9.5606447, 49.1774792],[9.5606433, 49.1774781] ]]}` Sieh hierzu auch: https://q-point.atlassian.net/wiki/spaces/PUB/pages/1781202973/REST+Grundlagen+von+Q+Exchange#GEO-Fences
projectManagerName string(100)	Vorname und Name des verantwortlichen Bauleiters.
projectManagerEmail string(100)	E-Mail des verantwortlichen Bauleiters.
projectManagerPhone string(100)	Telefonnummer des verantwortlichen Bauleiters.
foremanName string(100)	Vorname und Name des verantwortlichen Poliers.
foremanEmail string(100)	E-Mail des verantwortlichen Poliers.
foremanPhone string(100)	Telefonnummer des verantwortlichen Poliers.
senderName string(100)	Vorname und Name der Person, welche die Bestellung übermittelt.
state string(50) required	Status der Bestellung: Enum: "requested" (unverbindliche Anfrage) , "ordered" (verbindliche Bestellung).
attachments list[attachment]	Optionale Liste von Attachments.
canceled bool default: false	Die Mischgutbestellung wird annulliert. Fehlt die Angabe, bleibt der bisherige Zustand unverändert bestehen. Eine Annullierung ist nur zulässig, nachdem die Bestellung zuvor bereits einmal übermittelt wurde. Der Versuch, eine unbekannte Bestellung zu annullieren, wird mit einem Returncode "409 Conflict" beantwortet.
canceledReason string(1000)	Fakultative Angabe zum Grund der Annullation. Ist lediglich für annullierte Bestellungen (canceled == true) von Bedeutung. Ansonsten wird der Feldinhalt ignoriert.
revision integer required must be greater than 0	Revisionsstand der Bestellung auf Seite des Auftraggebers. Hierbei handelt es sich um eine fortlaufende Revisionsnummer der Bestellung (zero based). Der Revisionsstand von aufeinanderfolgenden Änderungen muss nicht zwingend lückenlos sein. Allerdings muss eine Änderung immer einen höheren Revisionsstand aufweisen als der zuvor übermittelte Datensatz. Auf Seite des Mischgutlieferanten bzw. der Mischanlagen lediglich als Information und ist deshalb auch readonly.

Transport-Liste

Einträge in der Transport-Liste beschreiben in der Regel die ersten Transportfahrten der eingesetzten LKWs. Es handelt sich damit nicht um den vollständigen Transportplan. Wird eine Transportliste angeführt, entfallen stattdessen die allgemeinen Angaben zum Transport bzw. die Felder "deliveryTerm", "countOfVehicles" sowie "loadingCapacity".

Object (transport)
quantity decimal(10,3) required must be greater than 0	Geplante Lademenge.
quantityUnit string(40) required	Masseinheit der Lademenge.
scheduledDepartureDt datetime required	Geplanter Abfahrtszeitpunkt auf der Mischanlage.
vehicleIdentifier string(100) required	Kennung des virtuellen Fahrzeugs. Hierbei handelt es sich um eine freie Bezeichnung (z:B "Fz 1", "Fz 2") oder falls bekannt, um das spezifische Kennzeichen.
vehicleTypeIdentifier string(100) required	Kennung des eingesetzten Fahrzeugtyps.
deliveryTerm string(40) required	Lieferkonditionen nach "International Commercial Terms". Zulässig sind: 'EXW': Ex Works bzw. Ab Werk 'DAP': Delivered at Place bzw. Frei Baustelle

Artikel-Liste

Liste mit den bestellten Mischgut-Artikel. Jeder Eintrag beschreibt einen Artikel, die Liefermenge inkl. Masseinheit sowie die Lieferreihenfolge.

Object (article)
sequenceNumber integer required must be greater than 0	Reihenfolge (one based) in der das bestellte Mischgut geliefert wird.
articleIdentifier string(100) required	Artikelnummer des bestellten Mischguts.
articleName string(100)	Artikelbezeichnung des bestellten Mischguts.
appraisalIdentifier string(100)	Kennung der Produktdeklaration (Eignungsprüfung) des gelieferten Mischguts. in der Regel eine Nummer.
quantity decimal(10,3) required must be greater than 0	Bestellmenge des spezifizierten Artikels.
quantityUnit string(40) required	Masseinheit der Mengenangabe. Alle in der Liste eingetragenen Masseinheiten müssen vom selben Einheiten-Type abstammen (beispielsweise "Masse" oder "Volumen". Ein Verstoss gegen diese Bedingung wird mit einem Returncode "400 Bad Request" beantwortet.
scheduledDeliveryDt datetime conditionally required	Geplanter Lieferzeitpunkt. Abhängig von der eingestellten Lieferkondition besitzt der angegebene Zeitpunkt eine unterschiedliche Bedeutung: Handelt es sich um eine Bestellung mit der Lieferkondition (EXW: Ab Werk), besitzt der Lieferzeitpunkt die Bedeutung "Lieferbeginn ab Mischwerk". Handelt es sich um eine Bestellung mit der Lieferkondition (DAP: Frei Baustelle), besitzt der angegebene Lieferzeitpunkt die Bedeutung "Ankunft auf Baustelle". Beim ersten Eintrag in der Artikelliste (sequenceNumber = 1) ist die Angabe eines Lieferzeitpunkts Pflicht! Bei allen nachfolgenden Einträgen kann anstelle eines absoluten Lieferzeitpunkts auch eine relative Pausen-Dauer (deliveryInterruption) angegeben werden. Fehlen beide Werte, beginnt die Lieferung des Artikels unmittelbar nachdem die gesamte Bestellmenge des vorangehenden Artikels ausgeliefert ist. Sind beide Werte vorhanden, so erhält der geplante Lieferzeitpunkt Vorrang gegenüber dem Unterbruch.
deliveryInterruption int conditionally required must be greater than 0	Lieferunterbruch in Minuten. Dieser Wert wird anstelle eines geplanten Lieferzeitpunkts (scheduledDeliveryDt) angegeben. Damit beginnt die Lieferung mit dem angegebenen Unterbruch, nachdem die Bestellmenge des vorangehenden Artikels ausgeliefert wurde. Fehlt sowohl der geplante Lieferzeitpunkt als auch die Angabe eines Unterbruchs (NULL), erfolgt die Lieferung unmittelbar, d.h. ohne Unterbruch, nach der Vorangehenden. Sind beide Werte vorhanden, so erhält der geplante Lieferzeitpunkt Vorrang gegenüber dem Unterbruch.

Liste der Anhänge

Liste mit angehängten Dokumenten.

Object (attachment)
fielname string(300) required	Filename inklusive Extension (bspw: MyFile.pdf).
mimeType string(40) required	MIME-Type der Datei. Zulässige Typen sind: `image/jpeg, image/png, image/gif, application/pdf, application/msword, application/msexcel, text/plain, text/csv`
fileContent binary required	Datei-Inhalt Base64 codiert.

Response

200 - Ok Falls die adressierte Bestellung existiert und erfolgreich aktualisiert wurde.
201 - Created Falls die Bestellung neu angelegt wurde.

Response Body (mixtureOrders)

id
UUID
required

Systemübergreifende eindeutige ID (UUID) der Bestellung. Diese wird vom System festgelegt, welches die Entität anlegt. Die ID ist für den Anwender nicht sichtbar.

...

Restliche Felder gemäss Request Body. Die Werte werden so zurückgegeben, wie sie in Q Plant aktuell gespeichert sind.

Ausnahme hiervon bilden die Attachments. Analog zum GET, wird hier lediglich die Liste mit den Informationen zu den Attachments zurückgeliefert. Auf die Rückgabe der eigentlichen Dateiinhalte wird aus Effizienzgründen verzichtet.

400 - Bad Request Die Bestellung kann aufgrund eines Syntax-Fehlers im Request Body nicht entgegengenommen oder geändert werden. Die Beschreibung der Fehlerursache wird in Form eines Error-Objekts im Response Body zurückgeliefert.
409 - Conflict Die Bestellung kann aufgrund eines Konflikts nicht entgegengenommen oder geändert werden. Die Beschreibung der Fehlerursache wird in Form eines Error-Objekts im Response Body zurückgeliefert.

Mögliche Fehler

Annullierung während sich die Bestellung bereits in Ausführung befindet

Sobald auf dem Mischwerk Lieferscheine zu einer Mischgutbestellung entstehen, befindet sich diese in Ausführung. Ab diesem Zeitpunkt ist eine Annullation der Bestellung nicht mehr zulässig. Entsprechende Versuche werden mit einem Returncode "409 Conflict" und dem nachfolgenden Fehlerobjekt beantwortet:

Attribute	Value
errorIdentifier	MixtureOrderInExecution
errorMessage	These changes are not permitted because the mixture order is already in delivery
reason	Cancelation refused

Annullierung einer unbekannten Bestellung

Ein Annullierung ist nur zulässig, nachdem die Bestellung zuvor bereits einmal übermittelt wurde. Der Versuch, eine unbekannte Bestellung zu annullieren, wird mit einem Returncode "409 Conflict" und dem nachfolgenden Fehlerobjekt beantwortet:

Attribute	Value
errorIdentifier	OrderRefused
errorMessage	Only known orders can be canceled
reason	Mixture order unknown

Nachträgliche Änderung des Flags "hasTransportslots"

Das Flag mixtureOrders.hasTransportslots muss mit der ersten Übermittlung der Bestellung korrekt gesetzt werden und darf daraufhin nicht mehr verändert werden! Entsprechende Versuche werden mit einem Returncode "409 Conflict" und dem nachfolgenden Fehlerobjekt beantwortet:

Attribute	Value
errorIdentifier	ChangeNotPermitted
errorMessage	Subsequent changing of the flag "hasTransportslots" is not permitted
reason	Change Not Permitted

Nicht Plausible Transportzeitpunkte

Die übermittelte Mischgutbestellung umfasst Transportzeitpunkte, die nicht plausibel sind. Mindesten einer der geplanten Transporte (Einträge in transports) liegen zeitlich vor dem Lieferzeitpunkt des ersten Artikels. Dies ist nicht zulässig, weshalb die Bestellung mit einem Returncode "409 Conflict" abgelehnt wird.

Attribute	Value
errorIdentifier	ChangeNotPermitted
errorMessage	The mixture order transmitted includes transport times that are not plausible
reason	Change Not Permitted

Bestellung umfasst Artikel in unterschiedlichen Typen von Masseinheiten

Die übermittelte Mischgutbestellung umfasst Artikel in unterschiedlichen Typen von Masseinheiten. Beispielsweise Masse 't' und Volumen 'm3'. Dies ist nicht zulässig, weshalb die Bestellung mit einem Returncode "400 Bad Request" abgelehnt wird.

Attribute	Value
errorIdentifier	InvalidParameterValue
errorMessage	The mixture order transmitted includes articles in different types of measurement units
reason	Articles with different types of units of measure

Mischgutbestellung abfragen

GET https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}

GET https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}

Die Methode ruft eine einzelne, zuvor übermittelte Bestellung ab und gibt sie an den Client zurück. Hierfür muss die mixtureorderId der angeforderten Bestellung als Pfadparameter übergeben werden. Der Aufruf erfolgt ohne Inhalt im Request Body.

Path Params
mixtureOrderId UUID required	Systemübergreifende eindeutige ID (UUID) der Mischgutbestellung, wie vom System des Auftraggebers festgelegt.

Response

200 - OK

Request Body (mixtureOrders)
identifier string(100) required	Systemübergreifende Kennung der Bestellung. Diese wird an die Mischanlage übermittelt und anschliessend unverändert auf die Lieferscheine bzw. im QR-Code aufgedruckt oder dem Lieferschein-Datensatz mitgeführt. Auf der Baustelle dient diese Kennung anschliessend als Referenz, um den Lieferschein wieder der Bestellung zuzuordnen. Der Identifier wird vom System des Bestellers festgelegt und sollte eindeutig sein. Für die Mischanlage ist dieser Wert nicht von Bedeutung und deshalb readonly.
contractIdentifier string(100)	Kennung des Rahmenvertrags unter den diese Mischgutbestellung fällt. Der Rahmenvertrag wird zwischen Mischgutlieferant und Baufirma abgeschlossen. Er regelt die für das gesamte Bauvorhaben zu liefernden Mischgutartikel inkl. Abnahmemengen, sowie den vereinbarten Preis.
plantIDDirectories UUID conditionally required	ID (GUID) der liefernden Mischanlage aus Q Directories. Falls die Mischanlage in Q Directories registriert ist, kann der Besteller dies zur Referenzierung verwenden. Pflichtfeld, falls das Feld 'plantIdentifier' leer ist.
plantIdentifier string(100) conditionally required	Eindeutiger Identifier bzw. Bezeichnung der liefernden Mischanlage. Pflichtfeld, falls das Feld 'plantIDDirectories' leer ist ist. Referenziert (nur) in diesem Fall die Mischanlage.
goodsDirection string(40)	Warenflussrichtung aus Sicht des Empfängers der Bestellung. "outgoing" (Ware bzw. Material wird an den Kunden abgegeben bzw. geliefert), "incoming" (Ware bzw. Material wird vom Werk entgegengenommen bzw. angeliefert). Fehlt die Angabe, wird per Definition outgoing gesetzt.
deliveryTerm string(40) required	Lieferkonditionen nach "International Commercial Terms". Fehlt die Angabe, wird per Definition (EXW) "Ab Werk" gesetzt. Zulässig sind: 'EXW': Ex Works bzw. Ab Werk 'DAP': Delivered at Place bzw. Frei Baustellee
articles list[article] required	Liste der bestellten Mischgutartikel inkl. Menge und Angabe ihrer Lieferreihenfolge.
deliveryPerformance decimal(10,3) must be greater than 0	Für den Einbau benötigte Lieferleistung.
performanceUnit string(40) conditionally required	Masseinheit aller Leistungsangaben in der Bestellung. In der Regel [t/h]. Pflichtfeld, falls Wert 'deliveryPerformance' vorhanden ist.
roundTripDuration integer must be greater than 0	Geschätzte Umlaufdauer der Transportfahrzeuge [min]. Dies ist die Summe aus der Beladedauer auf dem Mischwerk, der Fahrzeit zur Baustelle, der Warte- und Entladedauer auf der Baustelle sowie der Rückfahrt zum Mischwerk.
expectedDeliveryEndDt datetime	Zeitpunkt, zu welchem voraussichtlich die letzte Lieferung auf der Baustelle ankommt.
countOfVehicles integer must be greater than 0	Geplante Anzahl der eingesetzten Transportfahrzeuge. Dies Angabe entfällt, wenn stattdessen eine detaillierte Transportliste "transports[]" mitgegeben wird.
loadingCapacity decimal(10,3) must be greater than 0	Ladekapazität der eingesetzten Transportfahrzeuge [t]. Dies Angabe entfällt, wenn stattdessen eine detaillierte Transportliste "transports[]" mitgegeben wird.
transports list[transport]	Optionale Liste der Transporte. Die Liste beschreibt in der Regel die ersten Transportfahrten der eingesetzten LKWs und damit nur ein Teil des gesamten Transportplans. Wird eine Transportliste angeführt, entfallen stattdessen die allgemeinen Angaben zum Transport bzw. die Felder "deliveryTerm", "countOfVehicles" sowie "loadingCapacity".
hasTransportslots bool	Die Bestellung verfügt über einen getrennten Transportplan. Hierbei handelt es sich um eine Liste aufeinanderfolgender und zeitlich geplanter Transportfahrten. Der Plan wird über einen gesonderten Endpunkt, in Form der Entität transportslots abgefragt. Siehe hierzu: Abschnitt "Transportplanung", GET tranportslots. Im Falle einer "dynamischen Transportplanung", wird die Liste während der Ausführung des Transports zyklisch durch das Bestellsystem aktualisiert und an die momentane Ausgangssituation angepasst.
annotation string(1000)	Anmerkungen oder Hinweise zur Bestellung vom Auftraggeber an den Mischgutlieferanten.
ordererName string(100)	Name des Auftraggebers.
ordererCompanyName string(100) required	Name der beauftragenden Firma, welche schlussendlich die Lieferung vom Mischgutlieferanten verrechnen wird.
ordererCompanyIdentifier string(100)	Eindeutige Firmenkennung der beauftragenden Firma (Unternehmens-ID oder Umsatzsteuer-Nummer).
ordererPostalAddress string(1000)	Zusammenhängender Informations-String mit der kompletten Postanschrift des Auftraggebers (Rechnungsanschrift).
siteIdentifier string(100) required	Eindeutige Kennung der Baustelle, an welche das Mischgut geliefert wird. Hierbei handelt es sich um die Baustellen- oder Projekt-Kennung aus dem System des Auftraggebers.
siteName string(100)	Name der Baustelle.
siteCostCenter string(100)	Kostenstelle der Baustelle auf Seite des Bestellers. In der Regel handelt es sich hierbei um die Kostenstelle des zugeordneten Bauleiters.
sitePostalAddress string(1000)	Zusammenhängender Informations-String mit der kompletten Postanschrift der Baustelle.
siteGeoPosition list[geopoint]	Liste von geoPoint-Objekten, welche jeweils die Geo-Position bzw. die Koordinaten von Anfang, Ende oder Wegpunkten der Baustelle umfassen.
siteArea geofence	Optionale Angabe des Geofence um das Baustellengelände. Das Geofence wird in Form eines Polygons im Geo-JSON-Format geliefert. Es handelt sich um einen linearen Ring d.h. eine Aufzählung der Polygon-Eckpunkte (longitude, latitude WGS 84 ) im Gegenuhrzeigersinn. Der letzte Punkt ist mit dem Ersten deckungsgleich, womit das Polygon vollständig geschlossen ist. Beispiel: `{"type": "Polygon","coordinates":[[ [9.5606433, 49.1774781],[9.5606482, 49.1774756],[9.5606496, 49.1774767],[9.5606447, 49.1774792],[9.5606433, 49.1774781] ]]}` Sieh hierzu auch: https://q-point.atlassian.net/wiki/spaces/PUB/pages/1781202973/REST+Grundlagen+von+Q+Exchange#GEO-Fences
projectManagerName string(100)	Vorname und Name des verantwortlichen Bauleiters.
projectManagerEmail string(100)	E-Mail des verantwortlichen Bauleiters.
projectManagerPhone string(100)	Telefonnummer des verantwortlichen Bauleiters.
foremanName string(100)	Vorname und Name des verantwortlichen Poliers.
foremanEmail string(100)	E-Mail des verantwortlichen Poliers.
foremanPhone string(100)	Telefonnummer des verantwortlichen Poliers.
senderName string(100)	Vorname und Name der Person, welche die Bestellung übermittelt.
state string(50) required	Status der Bestellung: Enum: "requested" (unverbindliche Anfrage) , "ordered" (verbindliche Bestellung).
attachments list[attachment]	Optionale Liste von Attachments.
canceled bool	Die Mischgutbestellung ist annulliert.
canceledReason string(1000)	Fakultative Angabe zum Grund der Annullation. Ist lediglich für annullierte Bestellungen (canceled == true) von Bedeutung.
revision integer required must be greater than 0	Revisionsstand der Bestellung auf Seite des Auftraggebers. Hierbei handelt es sich um eine fortlaufende Revisionsnummer der Bestellung (zero based). Der Revisionsstand von aufeinanderfolgenden Änderungen muss nicht zwingend lückenlos sein. Allerdings muss eine Änderung immer einen höheren Revisionsstand aufweisen als der zuvor übermittelte Datensatz. Auf Seite des Mischgutlieferanten bzw. der Mischanlagen lediglich als Information und ist deshalb auch readonly.

Transport-Liste

Einträge in der Transportliste beschreiben in der Regel die ersten Transportfahrten der eingesetzen LKWs. Es handelt sich damit nicht um den vollständigen Transportplan. Wird eine Transportliste angeführt, entfallen stattdessen in mixtureOrder die allgemeinen Angaben zum Transport bzw. die Felder "deliveryTerm", "countOfVehicles" sowie "loadingCapacity".

Object (transport)
quantity decimal(10,3) required must be greater than 0	Geplante Lademenge.
quantityUnit string(40) required	Masseinheit der Lademenge.
scheduledDepartureDt datetime required	Geplanter Abfahrtszeitpunkt auf der Mischanlage.
vehicleIdentifier string(100) required	Kennung des virtuellen Fahrzeugs. Hierbei handelt es sich um eine freie Bezeichnung (z:B "Fz 1", "Fz 2") oder falls bekannt um das spezifische Kennzeichen.
vehicleTypeIdentifier string(100) required	Kennung des eingesetzten Fahrzeugtyps.
deliveryTerm string(40) required	Lieferkonditionen nach "International Commercial Terms". Zulässig sind: 'EXW': Ex Works bzw. Ab Werk 'DAP': Delivered at Place bzw. Frei Baustelle

Artikel-Liste

Liste der bestellten Mischgut-Artikel. Jeder Eintrag beschreibt einen Artikel, die Liefermenge inkl. Masseinheit sowie die Lieferreihenfolge.

Object (article)
sequenceNumber integer required must be greater than 0	Reihenfolge (one based), in der das bestellte Mischgut geliefert wird.
articleIdentifier string(100) required	Artikelnummer des bestellten Mischguts
articleName string(100)	Artikelbezeichnung des bestellten Mischguts.
AppraisalIdentifier string(100)	Kennung der Produktdeklaration (Eignungsprüfung) des gelieferten Mischguts. in der Regel eine Nummer.
quantity decimal(10,3) required must be greater than 0	Bestellmenge des spezifizierten Artikels.
quantityUnit string(40) required	Masseinheit der Mengenangabe. Alle in der Liste eingetragenen Masseinheiten müssen vom selben Einheiten-Typ abstammen (beispielsweise "Masse" oder "Volumen"). Ein Verstoss gegen diese Bedingung wird mit einem Returncode "400 Bad Request" beantwortet.
scheduledDeliveryDt datetime conditionally required	Geplanter Lieferzeitpunkt. Abhängig von der eingestellten Lieferkondition besitzt der angegebene Zeitpunkt eine unterschiedliche Bedeutung: Handelt es sich um eine Bestellung mit der Lieferkondition (EXW: Ab Werk), besitzt der Lieferzeitpunkt die Bedeutung "Lieferbeginn ab Mischwerk". Handelt es sich um eine Bestellung mit der Lieferkondition (DAP: Frei Baustelle), besitzt der angegebene Lieferzeitpunkt die Bedeutung "Ankunft auf Baustelle". Beim ersten Eintrag in der Artikelliste (sequenceNumber = 1) ist die Angabe eines Lieferzeitpunkts Pflicht! Bei allen nachfolgenden Einträgen kann anstelle eines absoluten Lieferzeitpunkts auch eine relative Pausen-Dauer (deliveryInterruption) angegeben werden. Fehlen beide Werte, beginnt die Lieferung des Artikels unmittelbar nachdem die gesamte Bestellmenge des vorangehenden Artikels ausgeliefert ist. Sind beide Werte vorhanden, so erhält der geplante Lieferzeitpunkt Vorrang gegenüber dem Unterbruch.
deliveryInterruption int conditionally required must be greater than 0	Lieferunterbruch in Minuten. Dieser Wert wird anstelle eines geplanten Lieferzeitpunkts (scheduledDeliveryDt) angegeben. Damit beginnt die Lieferung mit dem angegebenen Unterbruch, nachdem die Bestellmenge des vorangehenden Artikels ausgeliefert wurde. Fehlt sowohl der geplante Lieferzeitpunkt als auch die Angabe eines Unterbruchs (NULL), erfolgt die Lieferung unmittelbar, d.h ohne Unterbruch, nach der Vorangehenden. Sind beide Werte vorhanden, so erhält der geplante Lieferzeitpunkt Vorrang gegenüber dem Unterbruch.

Liste der Anhänge

Liste mit angehängten Dokumenten

Object (attachment)

fielName
string(300)
required

Filename inklusive Extension (bspw: MyFile.pdf).

mimeType
string(300)
required

MIME-Type der Datei.

Zulässige Typen sind: image/jpeg, image/png, image/gif, application/pdf, application/msword, application/msexcel, text/plain, text/csv

404 - Not Found Falls die adressierte Ressource nicht existiert.

Transportplanung

Ein einzelner Transport-Slot entspricht der Abholung einer Mischgutfuhre durch einen LKW. Zu jeder Bestellung gehört eine unbestimmte Zahl von Transportslots, die über die Methoden dieses Endpunkts verwaltet werden. Die Verwaltung erfolgt stets als Liste im Kontext einer konkreten Bestellung. So ist bei jedem Methodenaufruf unter anderem die 'mixtureOrderId' der betroffenen Bestellung als Pfadparameter anzugeben.

Liste von Transportfahrten zur Bestellung übermitteln

PUT https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/transportslots

PUT https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/transportslots

Die Methode übermittelt zu einer vorhandenen Bestellung die Liste der Transport-Slots an die Mischanlage. Sämtliche Slots stehen im Request Body desselben Methodenaufrufs. Pro Bestellung gibt es nur eine Liste. Beim wiederholten Aufruf dieser Methode wird die jeweils zuvor übermittelte Liste mit der neuen überschrieben.

Bei Mischgutbestellungen mit einem Transportplan muss das Flag mixtureOrders.hasTransportslots aktiviert sein.

Path Params
mixtureOrderId UUID required	Eindeutige ID (UUID) der Mischgutbestellung, zu der die übermittelten Transportslot gehören.

Request Body

[
  {
    "id": "fa867d39-8512-49af-be92-e894e542c1b2",
    "scheduledDepartureDt": "2020-01-06T06:10:00",
	//...
  },
  {
    "id": "ed09f6a0-933b-49ed-a212-31b54d53e3fa",
    "scheduledDepartureDt": "2020-01-06T06:17:00",
	//...
  }
]

Request Body (transportSlots)
id uuid required	Systemübergreifende eindeutige ID (GUID) des Transport-Slots. Dieser wird vom Planungssystem festgelegt.
scheduledDepartureDt datetime required	Planmässiger Abfahrtszeitpunkt auf der Mischanlage.
quantity decimal(10,3) must be greater than 0	Geplante Lademenge.
quantityUnit string(40) conditionally required	Masseinheit zur Lademenge ('quantity'). Pflichtfeld, falls Lademenge vorhanden.
vehicleRegistrationNumber string(100)	Amtliches Kennzeichen des Transport LKW's bzw. des Zugfahrzeugs.
vehicleRegistrationNumberTrailer string(100)	Amtliches Kennzeichen des Aufliegers.
vehicleTypeName string(100)	Bezeichnung des eingesetzten Fahrzeugtyps.
loadingTemperature integer must be greater than 0	Geforderte Mischguttemperatur bei Verladung auf den LKW (Ganzzahl).
temperatureUnit string(40) conditionally required	Masseinheit der Temperaturangaben. Pflichtfeld, falls Wert für 'loadingTemperature' existiert. Zulässige Werte sind '°C' und 'F'.
docketId uuid	Lieferschein ID (ist dieser Wert gesetzt, gilt der Slot als erledigt).
docketNumber string(200)	Lieferschein Nummer (ist dieser Wert gesetzt, gilt der Slot als erledigt).

Response

200 - Ok Falls die Transportliste erfolgreich aktualisiert wurde.

Response Body

409 - Conflict Die Bestellung kann aufgrund eines Konflikts nicht entgegengenommen oder geändert werden. Die Beschreibung der Fehlerursache wird in Form eines Error-Objekts im Response Body zurückgeliefert.

Mögliche Fehler

Die Aktualisierung des Transportplans ist nicht zulässig, da die Bestellung bereits annulliert wurde

Es ist nicht zulässig, den Transportplan zu einer bereits annullierten Mischgutbestellung zu aktualisieren. Der Versuch wird mit einem Returncode "409 Conflict" und dem nachfolgenden Fehlerobjekt beantwortet:

Attribute	Value
errorIdentifier	MixtureOrderIsCanceled
errorMessage	These changes are not permitted because the mixture order is already canceled
reason	Update refused

Die Bestellung ist bereits in Ausführung und lässt sich deshalb nicht mehr annullieren

Der Versuch, eine bereits in Ausführung befindliche Bestellung zu annullieren, ist nicht zulässig. Der Versuch wird mit einem Returncode "409 Conflict" und dem nachfolgenden Fehlerobjekt beantwortet:

Attribute	Value
errorIdentifier	MixtureOrderInExecution
errorMessage	The order is already being processed and can therefore not be canceled
reason	Update refused

Die Warenflussrichtung lässt sich nachträglich nicht mehr verändern

Es ist nicht zulässig, die Warenflussrichtung einer bestehenden Mischgutbestellung zu ändern. Der Versuch wird mit einem Returncode "409 Conflict" und dem nachfolgenden Fehlerobjekt beantwortet:

Attribute	Value
errorIdentifier	GoodsDirectionChangeNotPermitted
errorMessage	A changes of "goodsDirection" for an existing order are not permitted
reason	Update refused

Liste von Transportfahrt zur Bestellung abfragen

GET https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/transportslots

GET https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/transportslots

Die Methode ruft alle Transportslots zu einer Bestellung ab.

Path Params
mixtureOrderId UUID required	Eindeutige ID (UUID) der Mischgutbestellung, zu der die abgerufenen Transportslot gehören.

Response

200 - OK

Response Body

Response Body (transportSlots)
id uuid required	Systemübergreifende eindeutige ID (GUID) des Transport-Slots. Dieser wird vom Planungssystem festgelegt.
scheduledDepartureDt datetime required	Planmässiger Abfahrtszeitpunkt auf der Mischanlage.
quantity decimal(10,3) must be greater than 0	Geplante Lademenge.
quantityUnit string(40) conditionally required	Masseinheit zur Lademenge ('quantity'). Pflichtfeld, falls Lademenge vorhanden.
vehicleRegistrationNumber string(100)	Amtliches Kennzeichen des Transport LKW's bzw. des Zugfahrzeugs.
vehicleRegistrationNumberTrailer string(100)	Amtliches Kennzeichen des Aufliegers.
vehicleTypeName string(100)	Bezeichnung des eingesetzten Fahrzeugtyps.
loadingTemperature integer must be greater than 0	Geforderte Mischguttemperatur bei Verladung auf den LKW (Ganzzahl).
temperatureUnit string(40) conditionally required	Masseinheit der Temperaturangaben. Pflichtfeld, falls Wert für 'loadingTemperature' existiert. Zulässige Werte sind '°C' und 'F'.
docketId uuid	Lieferschein ID (ist dieser Wert gesetzt, gilt der Slot als erledigt).
docketNumber string(200)	Lieferschein Nummer (ist dieser Wert gesetzt, gilt der Slot als erledigt).

Liste der Transportfahrten von Bestellung löschen

DELETE https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/transportslots

DELETE https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/transportslots

Die Methode löscht sämtliche Transport-Slots der Bestellung. Voraussetzung ist, dass die Lieferschein-Felder 'docketId' und 'docketNumber' des Slots noch leer sind. Ist ein Lieferschein zugeordnet, dann hat diese Fahrt bereits stattgefunden und kann nicht mehr gelöscht werden.

Path Params
mixtureOrderId UUID required	Eindeutige ID (UUID) der Mischgutbestellung, zu der die zu löschenden Transportslots gehören.

Response

200 - OK Falls die gesamte Transportliste entfernt wurde.

Transportfahrzeuge

Über den Endpunkt '\vehicles' können die Transportfahrzeuge verwaltet werden, welche die einzelnen Fuhren des bestellten Mischguts abholen. Die Daten der Fahrzeuge werden seitens der Mischanlage in die Lieferscheine aufgenommen.

Liste von Fahrzeugen anlegen

PUT https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles

PUT https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles

Die Methode übermittelt die Liste der Transportfahrzeuge, welche das bestellte Mischgut abholen werden. Analog zu den Transportslots gibt es auch bei Fahrzeugen nur eine Liste pro Bestellung. Bei wiederholtem Aufruf der Methode auf derselben Bestellung wird die jeweils zuvor übermittelte Liste durch eine neue überschrieben.

Path Params
mixtureOrderId UUID required	Eindeutige ID (UUID) der Mischgutbestellung, zu der die übermittelten Fahrzeuge gehören.

Request Body

Request Body (vehicles)
registrationNumber string(100) required	Amtliches Kennzeichen des Transport LKW's bzw. des Zugfahrzeugs. Muss innerhalb einer Bestellung eindeutig sein.
registrationNumberTrailer string(100)	Amtliches Kennzeichen des Aufliegers.
vehicleTypeName string(100)	Bezeichnung des eingesetzten Fahrzeugtyps.
grossWeightRating integer must be greater than 0	Maximal zulässiges Gesamtgewicht der gesamten Fahrzeugkombination (Zugfahrzeug inkl. Auflieger).
grossWeightRatingUnit string(40) conditionally required	Masseinheit des Gesamtgewichts. Pflichtfeld, falls 'grossWeightRating' angegeben ist.
driverInfo string(100)	Angaben zum Fahrer. In der Regel der Name und Vorname.
driverPhone string(100)	Mobiltelefonnummer des Fahrers.
carrierInfo string(100)	Angaben zur Speditionsfirma. In der Regel die Bezeichnung des Unternehmens.
preDrivingTime integer must be greater than 0	Lenkzeit vor Antritt der ersten Fuhre [min].
annotation string(1000)	Fakultative Hinweise zum Fahrzeug oder dessen Einsatz.

Response

200 - Ok Falls die Fahrzeugliste erfolgreich aktualisiert wurde.

Response Body

Liste von Fahrzeugen abfragen

GET https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles

GET https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles

Die Methode ruft die registrierten Transportfahrzeuge einer Bestellung ab.

Path Params
mixtureOrderId UUID	Eindeutige ID (UUID) der Mischgutbestellung, zu der die abgefragten Fahrzeuge gehören.

Response

200 - Ok

Response Body

Response Body (vehicles)
registrationNumber string(100) required	Amtliches Kennzeichen des Transport LKW's bzw. des Zugfahrzeugs. Muss innerhalb einer Bestellung eindeutig sein.
registrationNumberTrailer string(100)	Amtliches Kennzeichen des Aufliegers.
vehicleTypeName string(100)	Bezeichnung des eingesetzten Fahrzeugtyps.
grossWeightRating integer must be greater than 0	Maximal zulässiges Gesamtgewicht.
grossWeightRatingUnit string(40) conditionally required	Masseinheit des Gesamtgewichts. Pflichtfeld, falls 'grossWeightRating' angegeben ist.
driverInfo string(100)	Angaben zum Fahrer. In der Regel der Name und Vorname.
driverPhone string(100)	Mobiltelefonnummer des Fahrers.
carrierInfo string(100)	Angaben zur Speditionsfirma. In der Regel die Bezeichnung des Unternehmens.
preDrivingTime integer	Lenkzeit vor Antritt der ersten Fuhre [min].
annotation string(1000)	Fakultative Hinweise zum Fahrzeug oder dessen Einsatz.
currentGeoPosition geoPoint	Letzte Information zur Fahrzeug-Geoposition zum Zeitpunkt currentGeoPositionDt.
currentGeoPositionDt datetime	Zeitpunkt, zu welchem sich das Fahrzeug an dieser Position befand. Fehlt die Angabe einer Zeitzone, wird der Zeitwert als “locale time” interpretiert.

Liste von Fahrzeugen löschen

DELETE https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles

DELETE https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles

Die Methode löscht die gesamte Fahrzeugliste der adressierten Bestellung.

Path Params
mixtureOrderId UUID required	Eindeutige ID (UUID) der Mischgutbestellung, zu der die zu löschenden Fahrzeuge gehören.

Response

200 - OK Falls die gesamte Fahrzeugliste entfernt wurde.

Einzelnes Fahrzeug löschen

DELETE https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles/{registrationNumber}

DELETE https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles/{registrationNumber}

Die Methode löscht ein einzelnes Transportfahrzeug.

Path Params
mixtureOrderId UUID required	Eindeutige ID (UUID) der Mischgutbestellung, zu der das zu löschende Fahrzeug gehört.
registrationNumber string(100) required	Amtliches Kennzeichen des zu löschenden Fahrzeugs.

Response

200 - OK Falls das Fahrzeug aus der Liste entfernt wurde.
404 - Not Found Falls kein Fahrzeug mit dem angegebenen amtlichen Kennzeichen existiert.

Aktuelle Fahrzeugpositionen übermitteln

POST https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles/currentstates

POST https://[BaseUrl]/clientrelations/{clientRelationId}/mixtureorders/{mixtureOrderId}/vehicles/currentstates

Die Methode übermittelt die momentane Geo-Koordinaten und Zustandsinformationen einer Liste von Transportfahrzeugen, welche im Rahmen der Bestellung im Einsatz sind. Neue Fahrzeugdatensätze aktualisieren hierbei jeweils die bestehenden Informationen. Es handelt sich hierbei um Fahrzeuge aus der Liste der eingesetzten Transportfahrzeuge '\vehicles'.

Die Übermittlung der Fahrzeug-Position beginnt in der Regel während der Anfahrt oder aber spätestens mit dem Start der ersten Transportfahrt. Mit dem Abschluss der letzten Transportfahrt endet die Übermittlung der Fahrzeugpositionen.

Fahrzeugpositionen müssen mindestens alle 10 min aktualisiert werden. Steht das Fahrzeug und behält deshalb über einen längeren Zeitraum dieselbe Position, muss dieselbe Position mindestens alle 10 min übermittelt werden. Ist die Positionsinformation älter als 15 min, geht Q Plant davon aus, dass das Fahrzeug offline ist. Positionsinformationen, welche älter als 1h sind, werden innerhalb von Q Plant nicht mehr angezeigt!

Request Body (currentStates)
vehicleRegistrationNumber string(100) required	Amtliches Kennzeichen des Transport LKW's bzw. des Zugfahrzeugs.
currentGeoPosition geoPoint required	Momentane Fahrzeug-Geo Position.
currentGeoPositionDt datetime required	Zeitpunkt, zu welchem sich das Fahrzeug an dieser Position befand. Der Zeitpunkt wird durch das Device bestimmt, welches auch die Geoposition ermittelt. Eine Zeitsynchronisation lasst sich nicht in jedem Fall sicherstellen, weshalb die Möglichkeit von zeitlichen Abweichungen besteht.
deliveryNoteId uuid	Lieferschein-ID, falls das Fahrzeug aktuell beladen ist. Entfällt, solange das Fahrzeug leer unterwegs ist oder die ID nicht bekannt ist.
docketNumber string(200)	Lieferscheinnummer, falls das Fahrzeug aktuell beladen ist. Entfällt, solange das Fahrzeug leer unterwegs ist.
estimatedRemainingDriveDuration int must be greater or equal than 0	Geschätzte restliche Fahrdauer bis zur Zieldestination in 's'. Der Wert bezieht sich auf die momentane Geoposition 'currentGeoPosition’ sowie den Zeitpunkt ‘currentGeoPositionDt’. Der geschätzte Ankunftszeitpunkt ETA ergibt sich anschliessend, indem die Dauer zum Aufzeichnungszeitpunkt hinzuaddiert wird.
estimatedTimeOfArrivalDt datetime	Geschätzte Ankunftszeitpunkt “estimated time of arrival” des Fahrzeugs an der Zieldestination. Der Zeitpunkt wird aufgrund der Fahrzeugposition fortlaufend neu bestimmt.
isLoaded bool	true: Das Fahrzeug ist momentan beladen. false oder NULL: Das Fahrzeug ist momentan nicht beladen.
isPaused bool	true: Das Fahrzeug bzw. der Fahrer absolviert aktuell eine Ruhepause.

Request Body

Response:

201 - Created Falls die Positionsliste entgegengenommen wurde.