REST API V1 - Reference SiteX Delivery
Lizenzbedingung
Die Nutzung der Q Exchange API und dieser Dokumentation unterliegt den API Nutzungsbedingungen, welche Sie hier einsehen können. Copyright Q Point AG (2024) – Alle Rechte vorbehalten.
Über die SiteX Delivery Schnittstelle lassen sich Lieferscheine zu Mischgut oder anderen Artikeln an die Baustelle übermitteln. Die Schnittstelle wird von Q Plant, direkt von einem Wiegesystem oder einem Auftragsverarbeitungssystem eines Lieferanten aufgerufen, um Lieferscheine an Q Site zu übermitteln.
Übersicht
GET https://[RootUrl]/apiinfos | Liefert technische Informationen zur API |
POST https://[WsBaseUrl]/weighingdeliverynotes | Einen neuen Lieferschein zu Q Site übermitteln |
POST https://[BaseUrl]/weighingdeliverynotes/{deliveryNotesId}/documents POST https://[WsBaseUrl]/weighingdeliverynotes | Ein Lieferschein-Dokument (PDF) zu einem bestehenden Lieferschein an Q Site übermitteln |
URL's
API Root URL [RootUrl]
Hierbei handelt es sich um die Root URL des SiteX API's des spezifischen Q Site-Clusters (Instanz). Ein solcher Cluster umfasst jeweils die Arbeitsbereiche mehrerer unterschiedlicher Kunden bzw. Baufirmen. Zur Einhaltung regulatorischer Anforderungen und aus Gründen der Skalierung existieren in jeder geografischen Region (Europa-West, US, Asia, India, Australia, etc.) mehrere Q Site-Cluster. Sie 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://eu1-api.q-site.com
Workspace Base URL [WsBaseUrl]
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 und der Adressierung eines bestimmten Workspace (Arbeitsbereich der Baufirma). Sie folgt dem Schema: '..../vx/workspaces/{workspaceId}'. Die von Ihnen benötigte Workspace Base URL erhalten Sie zusammen mit dem Access-Key vom Q Point Support.
Sie lautet beispielsweise: https://eu1-api.site.com/v1/workspaces/2e85275a-2d00-4e59-8b12-d8f0f7b828e6
Technischen Informationen zur API
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": "v2",
"isDeprecated": false
},
{
"version": "v1",
"isDeprecated": true
}
]
//...
}Response Body(supportedApiVersions) | |
version | Einzelne vom Cluster bzw. Server unterstützten API Versionen (Bsp: "v2"). |
isDeprecated | 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. |
Lieferscheine
Übermittlung eines Lieferscheins
Über den Endpunkt lassen sich Lieferscheine an den Q Site Arbeitsbereich übermitteln.
POST https://[WsBaseUrl]/weighingdeliverynotes |
|---|
Mit dem Aufruf dieses Endpunktes wird ein neuer Lieferschein übermittelt. Dabei muss im Request Body ein Datensatz gemäss unten beschriebener Struktur übergeben werden, der mindestens alle Pflichtfelder enthält. Der Aufruf erfolgt ohne Parameter. Die 'id' des Lieferscheins ist optional und wird, falls nicht übergeben, von Q Site bestimmt.
Lieferscheindatensätze werden ähnlich wie rechtsverbindliche Dokumente behandelt. Einmal an den Kunden ausgegeben, lassen sie sich nicht mehr verändern. Ist dieser fehlerhaft, muss der betroffene Lieferschein storniert und anschliessend ein neuer Lieferschein mit einer neuen ID ausgestellt werden. Die Stornierung erfolgt, indem der Lieferscheindatensatz erneut mit einem POST-Aufruf übermittelt und dabei das Feld "canceled" (Standardwert: 'false') auf 'true' gesetzt wird. SiteX erlaubt lediglich die Stornierung bereits bestehender Lieferschein-Instanzen (bestimmt durch deren ID). Der Versuch, einen unbekannten Lieferschein zu stornieren, beantwortet das API mit einer Fehlermeldung beantwortet (HTTP-Statuscode: 400 Bad Request). Der Vorgang einer Stornierung ist dabei unumkehrbar. Ist eine bestimmte Lieferschein-Instanz (bestimmt durch deren ID) einmal storniert, lässt sie sich anschliessend nicht wieder aktivieren!
Request Body (weighingDeliveryNotes) | |
id | GUID des Lieferscheins. Dieser wird entweder vom System mitgeliefert, welches den Lieferschein erzeugt oder ansonsten vom Empfänger beim erstmaligen Speichern festgelegt. |
docketNumber | 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 | 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 | Eindeutige Kennung (Unternehmens-ID oder Umsatzsteuer-Nummer) des Unternehmens, welche das Mischgut liefert und anschliessend auch in Rechnung stellt. |
accountingCompanyName | Name der Firma, welche das Mischgut liefert und anschliessend auch in Rechnung stellt. |
accountingCompanyPostalAdress | Zusammenhängender Informations-String mit der kompletten Postanschrift des Unternehmens, welche das Mischgut liefert. |
cancelled | Der Lieferschein ist storniert und wird deshalb nicht verrechnet. |
deliveryTerm | Lieferkonditionen nach "International Commercial Terms". Zulässig sind: |
goodsDirection | 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 | Artikelnummer des gelieferten Mischguts. |
articleName | Artikelbezeichnung des gelieferten Mischguts. |
initialInspectionIdentifier | Kennung der Erstprüfung des gelieferten Mischguts (In der Regel eine Nummer). |
declarationOfPerformanceIdentifier | Kennung der Leistungserklärung des gelieferten Mischguts. |
tareWeight | Taragewicht in der Masseinheit 'tareUnit'. |
tareIdentifier | Signatur des Wiegevorgangs bei eichamtlich abgenommenen Wiegesystemen. Die Signatur bildet die Referenz zum eichamtlichen Speicher und wird zur Rückverfolgung des Wiegevorgangs herangezogen. |
tareIsManual | Das Taragewicht wurde nicht gemessen, sondern manuell durch den Anwender erfasst. |
tareExecutionDt | Ausführungszeitpunkt der Tara-Wiegung. Pflichtfeld, falls der Wert 'tareWeight' vorhanden ist. |
tareUnit | Masseinheit des Tara-Gewichtswerts. Pflichtfeld, falls der Wert 'tareWeight' vorhanden ist. |
grossWeight | Bruttogewicht in der Masseinheit 'grossUnit'. |
grossIdentifier | Signatur des Wiegevorgangs bei eichamtlich abgenommenen Wiegesystemen. Die Signatur bildet die Referenz zum eichamtlichen Speicher und wird zur Rückverfolgung des Wiegevorgangs herangezogen. |
grossIsManual | Das Bruttogewicht wurde nicht gemessen, sondern manuell durch den Anwender erfasst. |
grossExecutionDt | Ausführungszeitpunkt der Brutto-Wiegung. Pflichtfeld, falls der Wert 'grossWeight' vorhanden ist. |
grossUnit | Masseinheit des Brutto-Gewichtswerts. Pflichtfeld, falls der Wert 'grossWeight' vorhanden ist. |
quantity | Liefermenge des spezifizierten Artikels. |
quantityUnit | Masseinheit der Mengenangabe. |
vehicleRegistrationNumber | Amtliches Kennzeichen des Transport LKWs bzw. des Zugfahrzeugs. |
vehicleRegistrationNumberTrailer | Amtliches Kennzeichen des Aufliegers. |
vehicleTypeName | Bezeichnung des eingesetzten Fahrzeugtyps. |
carrierIdentifier | Kennung der Speditionsfirma. |
loadingTemperature | Mischguttemperatur bei Verladung auf den LKW (Ganzzahl). |
temperatureUnit | Masseinheit aller Temperaturangaben im Lieferschein. Pflichtfeld, falls 'loadingTemperature' vorhanden. Zulässige Werte sind '°C' und 'F'. |
orderId | 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 Auftraggebers bzw. Empfängers des Lieferscheins, zur Referenzierung und Zuordnung zur Bestellung. |
orderIdentifier | Kennung der zugrunde liegenden 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. |
projectIdentifier | 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 | 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 | Eindeutiger Identifer bzw. Bezeichnung der liefernden Mischanlage. Pflichtfeld, falls das Feld 'plantIDDirectories' (siehe oben) leer ist. |
supplierCustomerIdentifier | 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 | Zusammenhängender Informations-String mit der kompletten Postanschrift des Kunden. |
supplierSiteIdentifier | Kennung der Baustelle, an welche das Mischgut geliefert wurde. Hierbei handelt es sich um die Baustellen-Nummer aus dem ERP des Mischgutlieferanten. |
sitePostalAddress | Zusammenhängender Informations-String mit der kompletten Postanschrift der Baustelle. |
annotation | Allfällige Hinweise oder Anmerkungen des Lieferanten zur Lieferung. |
estimatedTimeOfDepartureDt datetime | Geschätzter Abfahrtszeitpunkt des Transportfahrzeugs im Mischwerk (ETD). Fehlt die Angabe, wird die der Wert durch Q Site berechnet und eingesetzt. |
estimatedTimeOfArrivalDt datetime | Geschätzter Ankunftszeitpunkt des Transportfahrzeugs auf der Baustelle (ETA). Fehlt die Angabe, wird die der Wert durch Q Site berechnet und eingesetzt. |
Response
Der Webhook erwartet von der API des Abonnenten eine der folgenden Antworten.
200 OK oder 201 Created Wenn der Lieferschein entgegengenommen wurde.
Mögliche Fehler
Die Übermittlung von Lieferscheinen ist nicht erlaubt
Die momentane Lizenz-Stufe des Arbeitsbereichs schliesst die Übermittlung von Lieferscheinen aus. Der betroffene Kunde muss sich hierzu beim Q-Point Support melden und seine Lizenz-Stufe entsprechend anpassen.
403 - Forbidden
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 |
Lieferschein-Dokument (PDF) übermitteln
POST https://[BaseUrl]/weighingdeliverynotes/{deliveryNotesId}/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 | Systemübergreifend eindeutige ID (UUID) des Lieferscheins. |
Header Params | |
Content-Type: | multipart/form-data
|
Request Body (Part) | |
Key “name” | “deliveryNote” |
Key “filename” | 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 | MIME Type des Dokuments. Momentan ist lediglich "application/pdf" zulässig. |
Value | [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
Die Übermittlung von Lieferscheinen ist nicht erlaubt
Die momentane Lizenz-Stufe des Arbeitsbereichs schliesst die Übermittlung von Lieferscheinen aus. Der betroffene Kunde muss sich hierzu beim Q-Point Support melden und seine Lizenz-Stufe entsprechend anpassen.
403 - Forbidden
Angegebener Lieferschein konnte nicht gefunden werden
404 - Not Found Es existiert kein Lieferschein mit der angegebenen ID.
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 |
POST https://[WsBaseUrl]/weighingdeliverynotes |
|---|
Dieser Endpunkt ergänzt den vorangehenden und bietet eine alternative Möglichkeit, ein Lieferschein im PDF-Dokument hochzuladen. Im Gegensatz zum vorangehenden Endpunkt wird die Lieferschein-ID nicht als Pfad-Variable, sondern Request-Body angegeben. Durch den konstanten Pfad bzw. URL ist dieser Endpunkt für die Verwendung als Callback-URL geeignet.
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 Überermittlungsreihenfolge bestimmt den Revisionszähler. Dies bedeutet, dass das zuletzt übermittelte Dokument den höchsten Revisionsstand besitzt und als aktuelles Dokument ausgewiesen wird.
Allfällige PDF-Metadaten in der Datei spielen keine Rolle und werden ignoriert.
Header Params | |
Content-Type: | multipart/form-data |
Request Body (Part: Lieferschein-ID) | |
Key “name” | “deliveryNoteId” |
ContentType | "text/plain" |
Value | Systemübergreifende eindeutige ID (UUID) des Lieferscheins (beispielsweise: d1b68673-ea86-4ba4-a689-a3959fb8b0cb). |
Request Body (Part: Lieferschein-Dokument) | |
Key “name” | “deliveryNote” |
ContentType | MIME Type des Dokuments. Momentan ist lediglich "application/pdf" zulässig. |
Value | [file in binary data] |
Response
201 - Created Das Lieferschein-Dokument wurde ordnungsgemäss gespeichert.
Mögliche Fehler
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
Die Übermittlung von Lieferscheinen ist nicht erlaubt
Die momentane Lizenz-Stufe des Arbeitsbereichs schliesst die Übermittlung von Lieferscheinen aus. Der betroffene Kunde muss sich hierzu beim Q-Point Support melden und seine Lizenz-Stufe entsprechend anpassen.
403 - Forbidden
Adressierter Workspace konnte nicht gefunden werden
Der durch die Base-URL adressierte Workspace konnte nicht gefunden werden.
404 - Not Found
Attribute | Value |
errorIdentifier | InvalidParameterValue |
errorMessage | Workspace not found |
reason | Workspace error |
Fehlender oder fehlerhafter Part für die Lieferschein-ID
Der Part des Request-Body für die Lieferschein-ID fehlt oder ist fehlerhaft.
400 - Bad Request
Attribute | Value |
errorIdentifier | InvalidParameterValue |
errorMessage | Missing deliveryNoteId form section |
reason | The deliveryNoteId field is required |
Ungültige Formatierung der Lieferschein-ID
Die angegebene Lieferschein-ID besitzt ein falsches Format.
400 - Bad Request
Attribute | Value |
errorIdentifier | InvalidParameterValue |
errorMessage | Non Guid value in deliveryNoteId form section |
reason | The value 'xyz' is not valid for deliveryNoteId |
Fehlender oder fehlerhafter Part mit dem Lieferschein-Dokument
Der Part des Request-Body mit dem Lieferschein-Dokument fehlt oder ist fehlerhaft.
400 - Bad Request
Attribute | Value |
errorIdentifier | InvalidParameterValue |
errorMessage | Missing or empty deliveryNote form section |
reason | Delivery note document is missing |
Der für das Lieferscheindokument festgelegte Content-Type wird nicht unterstützt
Der im Feld ContentType angegebene MIME-Type des Dokuments wird nicht unterstützt. Momentan ist lediglich "application/pdf" zulässig.
400 - Bad Request
Attribute | Value |
errorIdentifier | InvalidParameterValue |
errorMessage | The Content-type specified in deliveryNote form section is not supported |
reason | Unsupported Content-type |
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 |
Das übermittelte Lieferschein-Dokument kann nicht verarbeitet werden
Die übermittelte Datei ist korrupt oder besitzt das falsche Format. Das Dokument kann nicht verarbeitet werden.
400 - Bad Request
Attribute | Value |
errorIdentifier | InvalidParameterValue |
errorMessage | The content of the file is invalid or does not conform to the expected format |
reason | Invalid document content |