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 diese Schnittstelle werden die Lieferscheindaten der Bauprojekte zur Weiterverarbeitung internen Drittsysteme übermittelt bzw. weitergeleitet.

Übersicht

Technische Informationen zur API

Technische Informationen zur API
GET https://[RootUrl]/apiinfos	Abfragen von technischen Informationen zum API
Callback Methode zum Export von Lieferscheinen
PUT https://[CallbackURL-for-deliveryNotes]	Export von Lieferscheinen der Bauprojekte
Rückmeldung zur Verbuchung von Lieferscheinen
POST https://[WsBaseUrl]/deliveryNotes/{deliveryNotesId}/cleared	Rückmeldung zur Verbuchung eines Lieferscheins

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 geografische 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/v2/workspaces/2e85275a-2d00-4e59-8b12-d8f0f7b828e6

API Key

Für den Zugriff auf die in dem Dokument angeführten Endpunkte des API ist ein arbeitsbereichsbezogenen API-Key notwendig.

Technischen Informationen zur API

GET https://[RootUrl]/apiinfos

GET https://[RootUrl]/apiinfos

Eine GET-Abfrage auf die API Root-Url liefert technischen 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 System die Möglichkeit dem Anwender einen entsprechenden Hinweis anzuzeigen und ihn darauf hinzuweisen, dass ein Update des Systems notwendig ist.

Callback Methode zum Export von Lieferscheinen

Über den Endpunkt werden die Lieferscheine eines bestimmten Arbeitsbereichs an ein Drittsystem übermittelt. Die Übermittlung basiert auf einer Subscription, welche manuell durch den Administrator eingerichtet wird. Der spezifizierte Endpunkt wird durch das Drittsystem implementiert und bereitgestellt. Die “CallbackURL-for-deliveryNotes“ wird vom Drittsystem festgelegt und bei der Registrierung in Q Site eingetragen.

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

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

Request Body

{ 
"items": [
	 //... 
	]
}

Request Body (deliveryNotes)
projectId UUID required	GUID des Projekts bzw. der Baustelle in Q Site, welcher der Lieferschein zugeordnet wurde.
projectIdentifier string(100) required	Eindeutige Kennung des Projekts bzw. der Baustelle in Q Site, welcher der Lieferschein zugeordnet wurde.
projectName string(100) required	Name des Projekts bzw. der Baustelle in Q Site, welcher der Lieferschein zugeordnet wurde.
costCenter string(100)	Kostenstelle des Projekts in Q Site. In der Regel handelt es sich hierbei um die Kostenstelle des zugeordneten Bauleiters.
id UUID required	GUID des Lieferscheins.
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 des Mischwerks.
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, welche den Lieferschein ausgibt.
isRejected bool	Die Annahme der Lieferung wurde auf der Baustelle abgelehnt. Ursachen hierfür sind unter anderem Qualitätsmängel oder Fehllieferungen.
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 des Unternehmens, welche das Mischgut liefert.
accountingCompanyPostalAdress string(1000)	Zusammenhängender Informations-String mit der kompletten Postanschrift des Unternehmens, welche das Mischgut liefert.
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 aus Sicht des Lieferanten. "outgoing" (Ware bzw. Material wurde an den Kunden abgegeben), "incoming" (Ware bzw. Material wurde vom Kunden entgegengenommen).
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)	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 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)	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 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) in der Masseinheit "temperatureUnit".
handoverTemperature integer must be greater than 0	Mischguttemperatur (Ganzzahl) bei Entlad des LKW's auf der Baustelle in der Masseinheit "temperatureUnit".
temperatureUnit string(40) conditionally required	Masseinheit aller Temperaturangaben im Lieferschein. Pflichtfeld, falls 'loadingTemperature' vorhanden.
receiptDt datetime	Annahmezeitpunkt der Lieferung auf der Baustelle.
orderId UUID	ID der zugrunde liegende 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 string(100)	Kennung der zugrunde liegende 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.
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. Hierbei handelt es sich um die Angaben aus dem ERP des Mischgutlieferanten.
annotation string(1000)	Allfällige Hinweise oder Anmerkungen des Lieferanten zur Lieferung
recipientAnnotation string(1000)	Anmerkungen der Baustelle bzw. des Empfängers des Lieferscheins.
processingGeoPosition geopoint	Zum Lieferschein erfasste Geo-Position. In der Regel handelt es sich um die Einbauposition des Materials, die auf der Baustelle erfasst wird
deliveryNoteDocumentUrl string(1000)	URL zum Lieferscheindokument im PDF-Format. Hierbei handelt es sich um eine sogenannte “Shared Access Signature (SAS)”. Jeder, der die URL kennt kann anschliessend auf das Dokument zugreifen. Folgendes ist hierbei zu beachten: Die URL besitzt eine begrenzte Gültigkeitsdauer von einigen Tagen. Falls der Empfänger das Dokument weiterverwenden möchte, muss er dieses nach der Übermittlung herunterladen und lokal speichern. Mithilfe des Parameters ‘hash’ in der URL, kann der Empfänger bei Bedarf prüfen, ob sich das Dokument gegenüber einer vorangehenden Übermittlung verändert hat. Mit Ausnahme der angegebenen Parameter dürfen keinen Annahmen über den Aufbau der URL getroffene werden. Diese kann sich über den Versionsverlauf des API ändern!
recipientAttachments list[attachment]	Liste von Anhängen zum Lieferschein. In der Regel handelt es sich hierbei um Bilder oder Dokumente, die auf der Baustelle aufgenommen wurden. Die Anhänge stammen nicht vom Lieferanten, sondern wurden auf Seite des Empfängers hinzugefügt.

Object (attachment)
mimeType string(40) required	MIME Type des Dokuments (Beispielsweise: `"image/png”`).
filename string(300) required	Dateiname inklusive Extension (Beispielsweise: “25488662.pdf“).
annotation string(100)	Optionalen Anmerkungen oder Hinweise zur Datei.
fileUrl string(1000) required	URL zum Dokument. Hierbei handelt es sich um eine sogenannte “Shared Access Signature (SAS)”. Jeder, der die URL kennt kann anschliessend auf das Dokument zugreifen. Folgendes ist hierbei zu beachten: Die URL besitzt eine begrenzte Gültigkeitsdauer von einigen Tagen. Falls der Empfänger das Dokument weiterverwenden möchte, muss er dieses nach der Übermittlung herunterladen und lokal speichern. Mithilfe des Parameters ‘hash’ in der URL, kann der Empfänger bei Bedarf prüfen, ob sich das Dokument gegenüber einer vorangehenden Übermittlung verändert hat. Mit Ausnahme der angegebenen Parameter dürfen keinen Annahmen über den Aufbau der URL getroffene werden. Diese kann sich über den Versionsverlauf des API ändern!

Response

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

200 OK Wenn die Lieferscheinliste entgegengenommen wurde.
Weitere Infos zu den Response-Codes und der damit in Verbindung stehenden Fehlerbehandlung finden sich im nachfolgenden Abschnitt.

Hinweise zur Verwendung und Implementierung des Callbacks

Q Site übermittelt die Lieferscheine in einem durch die Subscription festgelegten Zeitintervall. Abhängig vom jeweiligen Einsatzzweck kann dies täglich zu einem bestimmten Zeitpunkt - oder in einem vorgegebenen Intervall (beispielsweise alle 15 min) sein. Zu den diskreten Ausführungszeitpunkten werden dann jeweils sämtliche seit der letzten Übermittlung hinzugekommenen und alle zwischenzeitlich geänderten Lieferscheine übermittelt.
Das Baustellenpersonal muss die Lieferscheine in Q Site annehmen, sobald die zugrunde liegende physische Lieferung auf der Baustelle angekommen bzw. entladen ist. Q Site exportiert die Lieferscheine, nachdem sie angenommen sind und sich dadurch im Status "Bestätigt" (confirmed), "Abgelehnt" (rejected) oder "Abgerechnet" (cleared) befindet. Die Lieferscheine im Zulauf bzw. im Status "Ausgegeben" (issued) sind von der Übermittlung ausgeschlossen.
Lieferscheine, dessen Annahme auf der Baustelle beispielsweise aufgrund einer Fehllieferung oder eines Qualitätsproblems abgelehnt wurden, sind im Export durch das Flag ‘isRejected’ gekennzeichnet.
Die erste Lieferscheinübermittlung beginnt zu dem Zeitpunkt, zu welchem die Subscription eingetragen wird. Es werden ausschliesslich Lieferscheine übermittelt, welche nach diesem Zeitpunkt angenommen oder geänderte wurden.
Die Lieferscheine werden mithilfe ihrer ID (uuid) über die Systemgrenzen hinweg eindeutig identifiziert.
Wie für alle Endpunkte des SiteX-API gilt auch für diesen Endpunkt das Prinzip des “Tolerant Reader“. Das Drittsystem muss diese Pattern implementieren und damit umgehen, dass Q Site mehr (und auch bislang unbekannte) Attribute liefert als das Drittsystem erwartet.
Das Baustellenpersonal besitzt die Möglichkeit, Zusatzinformationen wie die Einbauposition, Bilder, Kommentare, Temperaturwerte etc. zum Lieferschein zu erfassen. Diese Angaben werden ebenfalls an das Drittsystem übermittelt.
Die Anzahl der in einem Call übermittelten Entitäten ist auf 50 Datensätze beschränkt. Sind mehr als 50 Lieferscheine zu einem bestimmten Zeitpunkt zu übermitteln, folgen unmittelbar nacheinander mehrere Aufrufe. Dies ist insbesondere nach längeren Verbindungsunterbrüchen relevant, wenn viele Lieferscheine zur Übermittlung anstehen.
Der komplette Pfad (URL) des Endpunkts ist vom Drittsystem bestimmt und wird beim Registrieren bzw. Anlegen der Subscription durch den Administrator eingetragen. Diese URL kann bei Bedarf mit Parameter ergänzt werden.
In bestimmten Anwendungsszenarien ist das Drittsystem darauf angewiesen, eigene Informationen, wie beispielsweise eine Mandanten- oder Kundensystem-Kennung, bei dem Aufruf zu erhalten. Diese Anforderung lässt sich entweder mithilfe eines spezifischen Pfads oder von Parameter umsetzen:
- Spezifischer Pfad: https://api.acme.com/client4567/qsitedelivery
- Parameter: https://api.acme.com/qsitedelivery?client=4567
Das Drittsystem muss für den Callback-Endpunkt eine Testfunktion implementieren. Damit wird sowohl die Erreichbarkeit des Endpunkts als auch die ordnungsgemässe Entgegennahme der zugehörigen Entitäten geprüft. Im Detail handelt es sich um einen sogenannten "Verification Call". Hierbei wird der Endpunkt mit einem zusätzlichen Parameter https://[CallbackUrl]?verification=true aufgerufen und ein Test Body übermittelt. Der Aufruf muss innerhalb von 5 s mit einem Statuscode 200 OK beantwortet werden. Ansonsten ist der Test fehlgeschlagen.
Fehlerbehandlung - Q Site unterscheidet, abhängig vom zurückgelieferten HTTP Status Code, zwischen drei unterschiedlichen Fehlerkategorien: vorübergehende Übermittlungsfehler, anhaltende Übermittlungsfehler und inhaltliche Fehler. Die Fehlerkategorie entscheidet in der Folge über die Fehlerbehandlung. Weitere Informationen hierzu finden sich unter: REST Grundlagen zu Q Exchange, Abschnitt: Callback Subscriptions, Fehlerbehandlung und Status.

Rückmeldung zur Verbuchung von Lieferscheinen

Über den Endpunkt werden bestehende Lieferscheine von einem Drittsystem als verrechnet gemeldet. Damit ändert sich auch in Q Site der Status zu "Abgerechnet" (cleared). Änderungen sind danach nicht mehr möglich.

POST https://[WsBaseUrl]/deliveryNotes/{deliveryNotesId}/cleared

POST https://[WsBaseUrl]/deliveryNotes/{deliveryNotesId}/cleared