Lizenzbedingung

Übersicht

Die PlantX Weighing API ist eine REST-Schnittstelle zum System Q Plant, über die die Daten einer Fahrzeugverwiegung an Q Plant übermittelt und wieder abgerufen werden können. Sie kann von jedem Client aufgerufen werden, der sich zuvor für den Zugriff registriert hat.

Ladetickets abrufen - Ladetickets sind das Planungs-Pendant zum Lieferschein. Ähnlich wie bei Lieferscheinen stehen auf einem Ladeticket u.a. Zeitpunkt, Menge, Artikel, Mischanlage und Fahrzeug einer Mischgutverladung, sowie weitere Daten, die in diesem Prozess benötigt werden. Anders als beim Lieferschein handelt es sich jedoch nicht um ein Dokument des tatsächlichen Vorgangs, sondern um eines der Planung. Diese Daten haben in der Regel eine geringe Abweichung von den späteren tatsächlichen Daten auf dem Lieferschein.
Über die Wiegeschnittstelle können Wiegesysteme diese Ladetickets von Q Plant abrufen, um auf deren Basis die Wiege- und Verladevorgänge zu planen.
Bestellungen abrufen - Jedem Ladevorgang liegt eine Bestellung zugrunde. Über die Wiegeschnittstelle können diese Bestellungen abgefragt werden, um sie den Wiege- und Ladevorgängen zuzuordnen.
Lieferscheine übermitteln - Nach erfolgtem Wiege- und Verladevorgang stellt das Wiegesystem einen Lieferschein aus. Über die Schnittstelle kann es diesen Lieferschein direkt an Q Plant senden.

Technische Informationen zur API
GET https://[RootUrl]/apiinfos	Liefert technische Informationen zur API
Lieferscheine
POST https://[BaseUrl]/weighingdeliverynotes POST https://[BaseUrl]/plants/{plantId}/weighingdeliverynotes	Übermittelt einen neuen Lieferschein an Q Plant
POST https://[BaseUrl]/weighingdeliverynotes/{deliveryNotesId}/documents POST https://[BaseUrl]/plants/{plantId}/weighingdeliverynotes/{deliveryNotesId}/documents	Übermittelt das zu einem bestehen Lieferschein gehörende PDF-Dokument an Q Plant
Belade-Tickets
GET https://[BaseUrl]/plants/{plantId}/loadingtickets	Liefert eine aktuelle Liste der Belade-Tickets eines bestimmten Mischwerks
Mischgutbestellungen
GET https://[BaseUrl]/plants/{plantId}/mixtureorders	Liefert eine aktuelle Liste der Bestellungen eines bestimmten Mischwerks

URL's

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 Cluster Base 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 "plantXWeihingRole" 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: "v7")
isDeprecated bool default: false	Die angegebene Version ist veraltet und wird in absehbarer Zeit nicht mehr unterstützt. Dieser Hinweis gibt abhängigen System die Möglichkeit dem Anwender einen entsprechenden Hinweis anzuzeigen und ihn darauf hinzuweisen, dass ein Update des Systems notwendig ist.

Lieferscheine

Der Lieferschein ist der schriftliche Beleg einer erfolgten Mischgutlieferung mit allen relevanten Daten, u.a. Zeitpunkt, Artikel und Menge, sowie die zugrunde liegende Bestellung.

Neuen Lieferschein übermitteln

POST https://[BaseUrl]/weighingdeliverynotes

POST https://[BaseUrl]/weighingdeliverynotes
POST https://[BaseUrl]/plants/{plantId}/weighingdeliverynotes

Mit dem Aufruf dieses Endpunktes wird ein neuer Lieferschein übermittelt. Die Übermittlung muss hierbei ohne Verzögerung, d.h. maximal wenige Minuten nach dessen Ausstellung erfolgen.

Request Body (weighingDeliveryNotes)
id UUID	GUID des Lieferscheins. Dieser wird entweder vom System mitgeliefert, welches den Lieferschein erzeugt oder ansonsten von Q Plant 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 LKWs angenommen werden. Dieser Zeitpunkt wird durch die Mischanlage bzw. durch dasjenige System bestimmt, welche den Lieferschein ausgibt.
accountingCompanyIdentifier string(100)	Kennung der Betreiberfirma, welche den Artikel 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.
operatorCreated bool default: false	Bei dem Lieferschein handelt es sich um einen Handlieferschein.
collectedDocketNumber string(100)	Ein Lieferschein kann Bestandteil eines Sammellieferscheins sein. Ein Sammellieferschein ist ein Behälter für mehrere Lieferscheine. Dieser Wert ist gesetzt, falls der Lieferschein zu einem Sammellieferschein gehört.
deliveryTerm string(100) 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 und zu verrechnenden Mischguts.
articleName string(100)	Artikelbezeichnung des gelieferten und zu verrechnenden Mischguts.
producedArticleIdentifier string(100)	Artikelnummer des hergestellten Mischguts. Die Angabe entfällt, wenn der produzierte Artikel mit dem gelieferten bzw. verrechneten Artikel übereinstimmt.
producedArticleName string(100)	Artikelbezeichnung des produzierten Mischguts. Die Angabe entfällt, wenn der produzierte Artikel mit dem gelieferten bzw. verrechneten Artikel übereinstimmt.
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 eichamtliche 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 LKWs bzw. des Zugfahrzeugs.
vehicleRegistrationNumberTrailer string(100)	Amtliches Kennzeichen des Aufliegers.
vehicleTypeIdentifier string(100)	Kennung des eingesetzten Fahrzeugtyps.
carrierIdentifier string(100)	Kennung der Speditionsfirma.
siloIdentifier string(100)	Kennung des Mischgutsilos, aus welchem das Mischgut entnommen wurde.
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.
price decimal(10,3)	Gesamtbetrag des Artikels. Der Wert ist nur bei Barlieferscheinen gesetzt.
priceCurrency string(40)	Währungs-Kurzzeichen des Gesamtbetrags.
orderId UUID conditionally required	ID der zugrunde liegenden 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 Bestellers bzw. Empfängers des Lieferscheins, zur Referenzierung und Zuordnung zur Bestellung. Eine der beiden Angaben 'orderId' oder 'orderIdentifier' muss vorhanden sein, damit sich der Lieferschein der Bestellung zuordnen lässt.
orderIdentifier string(100) conditionally required	Kennung der zugrunde liegenden 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 und dem QR-Code hinzu. Sie dient auf Seite des Bestellers bzw. Empfängers des Lieferscheins, zur Referenzierung und Zuordnung zur Bestellung. Eine der beiden Angaben 'orderIdentifier' oder 'orderId' muss vorhanden sein, damit sich der Lieferschein der Bestellung zuordnen lässt.
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	Eindeutige Kennung 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.
customerName string(100)	Name des Kunden.
customerPostalAddress string(100)	Postadresse (Strasse inklusive Hausnummer und allfällige weitere Angaben) des Kunden.
customerCity string(100)	Ortsangabe des Kunden.
customerPostalCode string(20)	PLZ 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.
siteName string(100)	Name der Baustelle.
sitePostalAddress string(100)	Lieferadresse (Strasse inklusive Hausnummer und allfällige weitere Angaben) der Baustelle.
siteCity string(100)	Ortsangabe zur Baustelle.
sitePostalCode string(20)	PLZ der Baustelle.
annotation string(500)	Allfällige Hinweise oder Anmerkungen des Lieferanten zur Lieferung.
executiveUser string(100)	Name des ausführenden Wiegemeisters.

Response

201 - Created Falls der Lieferschein neu angelegt wurde.

Response Body (weighingDeliveryNotes)
id UUID required	Systemübergreifende eindeutige ID (UUID) des Lieferscheins.
...	Restliche Felder gemäss Request Body. Die Werte werden so zurückgegeben, wie sie in Q Plant aktuell gespeichert sind.

Mögliche Fehler

400 - Bad Request Der Lieferschein kann aufgrund eines Syntax-Fehlers im Request Body nicht entgegengenommen werden. Die Beschreibung der Fehlerursache wird in Form eines Error-Objekt im Response Body zurückgeliefert.

Lieferschein existiert bereits

Neben der ID muss auch die Kombination aus Lieferscheinnummer (docketNumber) und Ausgabedatum (issueDt) bei neuen Lieferschein-Datensätzen eindeutig sein, d.h. es darf keinen weiteren aktiven (nicht stornierten) Lieferschein mit denselben Informationen geben. Ein Verstoss gegen diese Bedingung werden mit einem Returncode "409 Conflict"und dem nachfolgenden Fehlerobjekt beantwortet:

409 - Conflict

Attribute	Value
errorIdentifier	InvalidParameterValue
errorMessage	Weighing delivery note already exists. The id and the combination of docketNumber and issueDt must be unique
reason	Not unique

Stornierung von Lieferscheinen

Q Plant folgt dem Grundsatz, dass sich Lieferscheine nach ihrer Ausgabe nicht mehr verändern lassen - ähnlich einem Papierdokument, welches sich einmal ausgedruckt auch nur noch bedingt ändern lässt. Sollte ein Lieferschein falsch ausgestellt worden sein, muss dieser storniert und durch einen neuen korrekten Lieferschein ersetzt werden. Da es sich bei dem korrigierten um einen neuen Lieferschein bzw. zusätzliche Instanz handelt, besitzt dieser eine neue ID sowie eine neue Lieferscheinnummer. Dieses Vorgehen erlaubt es, Korrekturen von Lieferinformationen auch über Systemgrenzen hinweg nachvollziehbar weiterzuvermitteln. Eine Stornierung kann hierbei immer nur durch den Herausgeber des Original-Lieferscheins erfolgen. Dies ist in unserem Anwendungsfall im Allgemeinen ein angeschlossenes Wiegesystem.

Damit ein angeschlossenes Wiegesystem die Möglichkeit erhält, einen bestehenden Lieferschein zu stornieren, bietet das API im Rahmen der WeighingDeliveryNotes-Entität, das Feld "cancelled" (Defaultwert: 'false'). Zur Stornierung wird dieses auf 'true' gesetzt. Die Stornierung eines Lieferscheins ist sowohl bei der erstmaligen Übermittlung als auch nachträglich durch eine erneute Übermittlung möglich. In beiden Fällen wird hierzu der entsprechende POST Endpunkt aufgerufen. Das erstgenannte Szenario tritt ein, wenn der Anwender auf dem Mischwerk den Lieferschein storniert, bevor er an Q Plant übermittelt wird. So erhält Q Plant anschliessend den Lieferschein bereits storniert. Die Übermittlung dient hierbei lediglich der vollständigen Dokumentation innerhalb von Q Plant.
Der zweite Fall ist der Regelfall. Die Stornierung erfolgt auf dem Wiegesystem, nachdem der Lieferschein bereits erstmalig an Q Plant übermittelt wurde. Das Wiegesystem schickt den Datensatz nun ein zweites Mal, mit dem gesetzten "cancelled"-Flag. Der Vorgang einer Stornierung ist hierbei unumkehrbar. Ist eine bestimmte Lieferschein-Instanz (Bestimmt durch deren ID) einmal storniert, lässt sich diese anschliessend nicht wieder aktivieren.

Für die Übermittlung der Lieferscheine gilt der Grundsatz, dass sich Lieferscheinen nur einmalig an Q Plant übermitteln lassen. Wiederholte Versuche, einen gültigen Lieferschein zu übermitteln ("cancelled" == false), beantwortet das System bzw. API mit einer Fehlermeldung (HTTP Status Code: 409 Conflict "resource already exists"). Durch diese Einschränkung ist gleichzeitig auch sichergestellt, dass sich ein bereits stornierter Lieferschein nicht wieder aktivieren lässt.

Im Falle einer nachträglichen Stornierung, ignoriert das API neben dem "cancelled"-Flag alle restlichen Attribute des übermittelten Lieferschein-Datensatzes. Dadurch wird eine Mutation des Lieferscheins verhindert. Im Gegensatz zu der erstmaligen Übermittlung, ist an dieser Stelle jedoch auch ein mehrfacher Aufruf möglich. Da die Attribute ignoriert werden und der Lieferschein bereits storniert ist, bleibt der Aufruf jedoch ohne Auswirkung.

Lieferschein-Dokument (PDF) übermitteln

POST https://[BaseUrl]/weighingdeliverynotes/{deliveryNotesId}/documents

POST https://[BaseUrl]/weighingdeliverynotes/{deliveryNotesId}/documents
POST https://[BaseUrl]/plants/{plantId}/weighingdeliverynotes/{weighingdeliveryNotesId}/documents

Mit dem Aufruf dieses Endpunktes lässt sich ein PDF-Dokument zu einem bestehenden Lieferschein hochladen. Im Gegensatz zu den restlichen Endpunkten handelt es sich hierbei um einen multipart/formdata Request.

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.

Allfällige PDF-Metadaten in der Datei spielen keine Rolle und werden ignoriert.

Path Params
weighingdeliveryNotesId UUID required	Systemübergreifend eindeutige ID (UUID) des Lieferscheins.

Header Params

Content-Type:
required

multipart/form-data

Request Body (Part)
Key “name” required	“deliveryNote”
Key “filename” required	Dateiname des übermittelten Dokuments, beispielsweise "MyDocument_1.pdf" Die Dokumentenbezeichnung ist hierbei grundsätzlich unerheblich. Allerdings muss der Name zwingend durch ein Postfix '_X' mit Angabe des Revisionszählers (one based) ergänzt werden. Die einzelnen Werte müssen nicht zwingend fortlaufend sein. Ein bestimmter Revisionsstand lediglich einmal übermittelt werden. Die Angabe eines korrekten Revisionszählers ist Pflicht, ansonsten antwortet der Aufruf mit 400 Bad Request.
ContentType required	MIME Type des Dokuments. Momentan ist lediglich "application/pdf" zulässig.
Value required	[file in binary data]

Response

202 - Accepted Das Lieferschein-Dokument wurde ordnungsgemäss entgegengenommen. Die Speicherung und Indexierung erfolgt asynchron zu einem späteren Zeitpunkt.

Mögliche Fehler

Angegebener Lieferschein konnte nicht gefunden werden

404 - Not Found Es existiert kein Lieferschein mit der angegebenen ID.

Angegebenes Mischwerk konnte nicht gefunden werden

404 - Not Found Es existiert kein Mischwerk mit der angegebenen ID.

Mehrdeutige Mischwerkzuordnung

Der zuvor gespeicherte strukturierte Lieferscheindatensatz besitzt eine andere Mischwerkszuordnung als das in der URL angegebene Mischwerk.

409 - Conflict

Ungültiger Media-Type

Der Header zur Festlegung des Content-Types fehlt oder ist falsch. Es wird lediglich der Typ "multipart/form-data" unterstützt.

415 - Unsupported Media Type

Der angegebenen Mime-Type des Lieferscheins wird nicht unterstützt

Der im Response-Body angegeben Mime-Type wird nicht unterstützt. Momentan wird lediglich "application/pdf" unterstützt.

400 - Bad Request

Attribute	Value
errorIdentifier	InvalidParameterValue
errorMessage	The Content-type specified in deliveryNote form section is not supported
reason	Unsupported Content-type

File Content fehlt

Der Part ist leer. Der Content fehlt.

400 - Bad Request

Attribute	Value
errorIdentifier	InvalidParameterValue
errorMessage	Content not found
reason	No content

Falsche Formatierung der Dateibezeichnung

Die angegebene Dateibezeichnung ist nicht gemäss Spezifikation formatiert. Vermutlich fehlt das Postfix '_X' mit Angabe des Revisionszählers (one based) .

400 - Bad Request

Attribute	Value
errorIdentifier	InvalidParameterValue
errorMessage	The specified file name is not formatted according to the specification
reason	Invalid filename

Die angegebene Datei-Erweiterungen stimmt nicht mit dem erwarteten Content-Type überein

Momentan sind lediglich PDF-Dokumente zulässig (application/pdf). Die angegebene Datei-Erweiterung ist hingegen nicht “.pdf”.

400 - Bad Request

Attribute	Value
errorIdentifier	InvalidParameterValue
errorMessage	The specified file extension does not correspond to the Content-Type
reason	Invalid file extension

Ungültiger Dateiinhalt

Der Inhalt der Datei ist ungültig oder entspricht nicht dem erwarteten Format. Dieser Fehler tritt etwa ein, wenn es sich bei der angehängten Datei nicht um ein PDF-Dokument handelt.

400 - Bad Request

Attribute	Value
errorIdentifier	InvalidContent
errorMessage	The content of the file is invalid or does not conform to the expected format
reason	Invalid document content

Belade-Tickets

Liste aller Belade-Tickets abfragen

GET https://[BaseUrl]/plants/{plantId}/loadingtickets?from={datetime}&to={datetime}&skip={integer}&take={integer}

GET https://[BaseUrl]/plants/{plantId}/loadingtickets?from={datetime}&to={datetime}&skip={integer}&take={integer}

Liefert eine Liste der für ein Mischwerk geplanten Belade-Tickets. Es wird je Bestellung das jeweils nächste Beladeticket aus dem angegebenen Zeitraum geliefert.

Path Params
plantId UUID required	ID der Mischanlage

Query Params
from datetime required	Beginn des Bezugszeitraums der Tickets. Der Aufruf liefert sämtliche Tickets, deren geplanten Ausführungszeitpunkt (scheduledExecutionDt) sich mit dem angegebenen Bezugszeitraum schneidet.
to datetime required	Ende des Bezugszeitraums der Tickets (Siehe vorangehendes Feld "from").
skip integer 0 <= Wert	Index im Resultset. Anzahl Datensätze, welche in Resultset zu überspringen sind. Wird verwendet, um nacheinander mehrere Data-Pages abzurufen.
take integer 0 < Wert <= default default: 200	Maximale Anzahl der als Response Body zurück gelieferten Datensätze. Falls das Feld fehlt oder der angegebene Wert über dem Default-Wert liegt, liefert die Anfragen maximal die als "default" festgelegte Anzahl Datensätze!
allTickets boolean default: false	Mit true wird angegeben, dass alle Beladetickets im Zeitraum geliefert werden, nicht nur das jeweils Nächste.

Response

200 - OK

Response Body

{ 
"pagination": { 
			"offset": 0,
	 		"count": 50,
			"total": 465,
			"hasMoreEntries":  true.
	 },
"items": [
	 //... 
	]
}

Response Body (loadingtickets)
id UUID required	Eindeutige GUID des Tickets. Wird durch Q Plant festgelegt.
mixtureOrderId UUID required	Systemübergreifend eindeutige ID (GUID) der zugrunde liegenden Bestellung.
mixtureOrderIdentifier string(100) required	Systemübergreifende Kennung der zugrunde liegenden Bestellung.
scheduledExecutionDt datetime required	Geplanter Ausführungszeitpunkt.
quantity decimal(10,3) must be greater than 0 required	Geplante Lademenge für das Fahrzeug.
quantityTrailer decimal(10,3) must be greater than 0	Geplante Lademenge für den Fahrzeuganhänger.
quantityUnit string(20) required	Masseinheit der Lademenge.
articleId UUID required	ID des bestellten Mischguts.
articleIdentifier string(100) required	Artikelnummer des bestellten Mischguts.
articleName string(100)	Artikelbezeichnung des bestellten Mischguts.
annotation string(1000)	Interne Anmerkungen oder Hinweise zur Beladung.
vehicleRegistrationNumber string(100)	Amtliches Fahrzeug-Kennzeichen (normalisiert d.h. Grossbuchstaben und ohne Leerzeichen).
vehicleTypeIdentifier string(100)	Kennung des eingesetzten Fahrzeugtyps
vehicleRegistrationNumberTrailer string(100)	Amtliches Anhänger-Kennzeichen (normalisiert, d.h. Grossbuchstaben und ohne Leerzeichen).
changedDt datetime required	Zeitpunkt der letzten Mutation. Lässt sich zur Änderungserkennung oder zur Konfliktlösung verwenden.

Mischgutbestellungen

Liste aller Mischgutbestellungen abfragen

GET https://[BaseUrl]/plants/{plantId}/mixtureorders?from={datetime}&to={datetime}&skip={integer}&take={integer}

GET https://[BaseUrl]/plants/{plantId}/mixtureorders?from={datetime}&to={datetime}&skip={integer}&take={integer}

Liefert eine Liste der für ein Mischwerk geplanten Bestellungen.

Path Params
plantId UUID required	ID der Mischanlage.

Query Params
from datetime required	Beginn des Bezugszeitraums der Bestellungen. Der Aufruf liefert sämtliche Bestellungen, deren Lieferstart (scheduledDeliveryBeginDt) sich mit dem angegebenen Bezugszeitraum schneidet.
to datetime required	Ende des Bezugszeitraums der Bestellungen (Siehe vorangehendes Feld "from").
skip integer 0 <= Wert	Index im Resultset. Anzahl Datensätze, welche in Resultset zu überspringen sind. Wird verwendet, um nacheinander mehrere Data-Pages abzurufen.
take integer 0 < Wert <= default default: 200	Maximale Anzahl der als Response Body zurück gelieferten Datensätze. Falls das Feld fehlt oder der angegebene Wert über dem default-Wert liegt, liefert die Anfragen maximal die als "default" festgelegte Anzahl Datensätze!

Response

200 - OK

Response Body

{ 
"pagination": { 
			"offset": 0,
	 		"count": 50,
			"total": 465,
			"hasMoreEntries":  true,
	 },
"items": [
	 //... 
	]
}

Response Body (mixtureOrders)
id UUID required	Systemübergreifend eindeutige ID (GUID) der Mischgutbestellung. Diese wird vom System des Auftraggebers oder von Q Plant festgelegt. Diese dient als Referenz zu allen Inhalten der Bestellung (bspw. Lieferscheine).
identifier string(100) required	Systemübergreifende Kennung der Bestellung. Diese wird vom Besteller 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.
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.
goodsDirection string(40) required	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).
deliveryTerm string(100) required	Lieferkonditionen nach "International Commercial Terms": '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.
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.
expectedDeliveryEndDt datetime	Zeitpunkt, zu welchem voraussichtlich die letzte Lieferung auf der Baustelle ankommt.
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.
annotationPlant string(1000)	Interne Anmerkungen oder Hinweise zur Bestellung vom Disponenten auf der Mischanlage.
annotationPlantDeliveryNote string(500)	Anmerkungen des Mischgutlieferanten zur Lieferung. Der Hinweistext wird durch das Werkspersonal in Q Plant erfasst und anschliessend durch das Wiegesystem auf sämtlichen Lieferscheinen der Bestellung angeführt.
annotationOrderer string(1000)	Anmerkungen oder Hinweise des Auftraggebers bzw. Kunden zur Bestellung.
customerId string(100) required	ID (GUID) des Kunden bzw. Auftraggebers aus dem Kundenstamm von Q Plant.
customerIdentifier string(100) required	Kennung des Kunden aus dem Kundenstamm von Q Plant. In der Regel handelt es sich hierbei um die Kundennummer aus dem ERP des Mischgutlieferanten.
customerName string(100) required	Name des Kunden aus dem Kundenstamm von Q Plant.
customerPostalAddress string(100)	Rechnungsanschrift des Kunden - Strasse.
customerCity string(100)	Rechnungsanschrift des Kunden - Ortschaft.
customerPostalCode string(100)	Rechnungsanschrift des Kunden - Postleitzahl.
customerCountry string(20)	Rechnungsanschrift des Kunden - Landeskennung gemäss ISO 3166-1.
siteId string(100) required	ID (GUID) der Baustelle aus dem Baustellenstamm von Q Plant.
siteIdentifier string(100) required	Kennung der Baustelle aus dem Baustellenstamm von Q Plant. In der Regel handelt es sich hierbei um die Baustellennummer aus dem ERP des Mischgutlieferanten.
siteName string(100) required	Name der Baustelle aus dem Baustellenstamm von Q Plant.
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(100)	Rechnungsanschrift der Baustelle - Strasse.
siteCity string(100)	Rechnungsanschrift der Baustelle - Ortschaft.
sitePostalCode string(100)	Rechnungsanschrift der Baustelle - Postleitzahl.
siteCountry string(20)	Rechnungsanschrift der Baustelle - Landeskennung gemäss ISO 3166-1.
projectManagerName string(100)	Name und Vorname des verantwortlichen Bauleiters.
projectManagerEmail string(100)	E-Mail des verantwortlichen Bauleiters.
projectManagerPhone string(100)	Telefonnummer des verantwortlichen Bauleiters.
foremanName string(100)	Name und Vorname des verantwortlichen Poliers.
foremanEmail string(100)	E-Mail des verantwortlichen Poliers.
foremanPhone string(100)	Telefonnummer des verantwortlichen Poliers.
changedDt datetime required	Zeitpunkt der letzten Mutation. Lässt sich zur Änderungserkennung oder zur Konfliktlösung verwenden.

Transport-Liste

Einträge in der Transportliste beschreiben in der Regel die ersten Transportfahrten der eingesetzten LKWs. Es handelt sich damit nicht um den gesamten Transportplan, sondern nur um die Liste und ersten Startzeiten der eingesetzten Transportfahrzeuge.

Object (transport)
entryId UUID required	ID (GUID) zu Identifizierung des Listeneintrags. Mit der ID lässt sich erkennen, ob es sich um einen bekannten oder neuen Listeneintrag handelt.
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-Artikeln. Jeder Eintrag beschreibt einen Artikel, die Liefermenge inkl. Masseinheit sowie die Lieferreihenfolge.

Object (article)
entryId UUID required	ID (GUID) zu Identifizierung des Listeneintrags. Mit der ID lässt sich erkennen, ob es sich um einen bekannten oder neuen Listeneintrag handelt.
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.
recipeId UUID	ID (GUID) des zu produzierenden Mischgutrezepts.
recipeIdentifier string(100)	Kennung des zu produzierenden Mischgutrezepts.
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 einer Lieferkondition (EXW: Ab Werk), besitzt der Lieferzeitpunkt die Bedeutung "Lieferbeginn ab Mischwerk". Handelt es sich um eine Bestellung mit einer 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.

public

REST API V8 - Reference PlantX Weighing

Lizenzbedingung

Übersicht

URL's

Technische Informationen zur API

Response

Response Body

Lieferscheine

Neuen Lieferschein übermitteln

Response

Mögliche Fehler

Lieferschein existiert bereits

Stornierung von Lieferscheinen

Lieferschein-Dokument (PDF) übermitteln

Response

Mögliche Fehler

Angegebener Lieferschein konnte nicht gefunden werden

Angegebenes Mischwerk konnte nicht gefunden werden

Mehrdeutige Mischwerkzuordnung

Ungültiger Media-Type

Der angegebenen Mime-Type des Lieferscheins wird nicht unterstützt

File Content fehlt

Falsche Formatierung der Dateibezeichnung

Die angegebene Datei-Erweiterungen stimmt nicht mit dem erwarteten Content-Type überein

Ungültiger Dateiinhalt

Belade-Tickets

Liste aller Belade-Tickets abfragen

Response

Response Body

Mischgutbestellungen

Liste aller Mischgutbestellungen abfragen

Response

Response Body