REST API V1 - Reference DirectoriesX

Owned by Marcel Pilger
Last updated: May 09, 2023 by Gerhard Hager
6 min read

Lizenzbedingung
Die Nutzung der Q Exchange API und dieser Dokumentation unterliegt den API Nutzungsbedingungen, welche Sie hier einsehen können. Copyright Q Point AG (2023) – Alle Rechte vorbehalten.

Übersicht

Technische Informationen zur API

Technische Informationen zur API

GET https://[RootUrl]/apiinfos

Abfragen von technischen Informationen zum API

Mischwerke

GET  https://[BaseUrl]/plants?region={string}&geoposition={string}&range={integer}&type={string}&includingDemo={boolean}

Liefert eine Übersichtsliste von Mischwerken, welche den Suchkriterien entsprechen.

GET https://[BaseUrl]/plants/{plantId}

Liefert alle Detailinformationen zu dem adressierten Mischwerk.

Artikel

GET https://[BaseUrl]/plants/{plantId}/articles

Liefert eine Übersichts- oder Auswahlliste der vom Mischwerk angebotenen Artikel.

GET https://[BaseUrl]/plants/{plantId}/articlesasphalt/{articleId}

Liefert die Detailinformationen des adressierten Artikels des Typs ‘asphalt’.

URL's

API Root URL [RootUrl]

Hierbei handelt es sich um die Root URL von Q Directories bzw. des DirectoriesX-API's. 

Zur Einhaltung regulatorischer Anforderungen und um die Latenzzeiten gering zu halten, besitzt jede geografische Region (Europa-West, US, Asia, India, Australia, etc) ihre eigene Q Directories-Instanz. Sie 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://eu-api.q-directories.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://eu-api.q-directories.com/ v1/

API Key

Für den Zugriff auf die in dem Dokument angeführten Endpunkte des API’s ist ein globaler API-Key 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
Response Body
{ "supportedApiVersions": [ { "version": "v1", "isDeprecated": false }, { "version": "v2", "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 erlaubt abhängigen Systemen, dem Anwender einen entsprechenden Hinweis anzuzeigen und ihn darauf hinzuweisen, dass ein Update des Systems notwendig ist.

 

Mischwerke

Diese Ressource repräsentiert das Mischwerks-Verzeichnis in Q Directories.

Suche nach Mischwerken

GET  https://[BaseUrl]/plants?region={string}&geoposition={string}&range={integer}&type={string}

GET  https://[BaseUrl]/plants?region={string}&geoposition={string}&range={integer}&type={string}

Liefert eine Liste von Mischwerken, welche den Suchkriterien entsprechen.

Path Params

plantId
UUID
required

Global eindeutige ID (UUID) des abgefragten Mischwerks

Query Params

region
string
conditionally required

Der Regionen-Identifier zur Eingrenzung der Suche auf eine Region. Mindestens einer der beiden Parameter ‘region’ oder ‘geoPosition’ ist Pflicht.

geoPosition
geoPoint
conditionally required

Die Geoposition zur Eingrenzung der Suche auf einen bestimmten Radius um diese Position. Mindestens einer der beiden Parameter ‘region’ oder ‘geoPosition’ ist Pflicht.

range
integer
default: 100

Der Suchradius in km um die gegebene Geoposition. Wird nur in Kombination mit dem Parameter ‘geoPosition’ verwendet.

type
string

Verfahrenstyp der Mischanlage ‚asphalt‘‚ ‘concrete‘, 'gravel’.

includingDemo
bool
default: false

Die Abfrage liefert neben den realen zusätzlich auch die Demo-Mischwerke. Dies sind mit dem Flag ‘isDemo’ gekennzeichnet.

Response

  • 200 - OK

Response Body (plants)

id
UUID
required

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

identifier
string(100)
required

Bezeichnung des Mischwerks.

type
string(100)
required

Verfahrenstyp der Mischanlage ‚asphalt‘‚ ‘concrete‘, 'gravel’.

geoPosition
geoPoint
required

Geo-Position des Mischwerks.

country
string(20)
required

Landeskennung gemäss ISO 3166-1

region
string(100)

Bundesland oder Region

postalAddress
string(100)
required

Strasse

city
string(100)
required

Ortschaft

postalCode
string(100)
required

Postleitzahl

isDemo
bool

Das Mischwerk ist nicht real, sondern existiert lediglich für Demonstrationszwecke. Dieses Feld wird ausschliesslich dann zurückgelieferte, wenn der Query-Parameter ‘includingDemo’ gesetzt wurde.

properties
string(500)
required

Semikolon getrennte Aufzählung der Eigenschaften des Mischwerks:
'digitalReady': Dieses Mischwerk besitzt die Voraussetzung für einen vollständig digitalen Bestell- & Lieferprozess. Damit existiert in den Detailinformationen auch eine ‘baseUrlApi’ für den Zugriff auf das API des Mischwerks.

 

Einzelnes Mischwerk nach ID abfragen

GET  https://[BaseUrl]/plants/{plantId}

GET  https://[BaseUrl]/plants/{plantId}

Liefert alle Detailinformationen zu dem adressierten Mischwerk.

Path Params

plantId
UUID
required

Global eindeutige ID (UUID) des abgefragten Mischwerks

Response

  • 200 - OK

Response Body (plants)

id
UUID
required

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

identifier
string(100)
required

Bezeichnung des Mischwerks.

alias
string(1000)

Semikolon getrennte Aufzählung von Alias d.h. alternative Mischwerksbezeichnungen (“also known as”). Die Bezeichnungen können mehrdeutig sein!

type
string(100)
required

Verfahrenstyp der Mischanlage ‚asphalt‘‚ ‘concrete‘, 'gravel’.

geoPosition
geoPoint
required

Geo-Position des Mischwerks.

country
string(20)
required

Landeskennung gemäss ISO 3166-1

region
string(100)

Bundesland oder Region

postalAddress
string(100)
required

Strasse

city
string(100)
required

Ortschaft

postalCode
string(100)
required

Postleitzahl

emailAddressOffice
string(100)

Allgemeine E-Mail-Adresse der Verwaltung

phoneOffice
string(100)

Telefonnummer Zentrale

fax
string(100)

Fax-Nummer

homepageUrl
string(1000)

URL der Homepage.

logoUrl
string(1000)

URL zum Unternehmens-Logo im PNG-Format. Hierbei handelt es sich um eine sogenannte “Shared Access Signature (SAS)”.

plantImageUrl
string(1000)

URL zum Anlagen-Bild im PNG-Format. Hierbei handelt es sich um eine sogenannte “Shared Access Signature (SAS)”.

phoneOfficeOders
string(100)

Telefonnummer für Mischgutbestellungen

emailAddressOrders
string(100

E-Mail-Adresse für Mischgutbestellungen

contactName
string(100)

Vollständiger Name des Kontaktes auf der Mischanlage

baseUrlApi
string(1000)

Base-URL des PlantX API’s zur digitalen Anbindung des Mischwerks. Damit besitzt das Mischwerk die Voraussetzung für einen vollständig digitalen Bestell- & Lieferprozess.

operatingIdentifier
string(100)

Betriebskennung oder -Nummer der Anlage.

loadingDuration
integer

Mittlere Beladedauer [s] (Mischgut)

unloadingDuration
integer

Mittlere Entladedauer [s] (Fräsgut)

productionPerformance
integer

Maximale Produktionsleistung (Nennleistung) der Mischanlage [t/h]

storageCapacity
integer

Gesamte Lagerkapazität an Heissmischgut [t]

plantArea
geofence

Geofence um das Werksgelände rund um die Mischwerksposition 'geoPosition'. Wird verwendet, um zu erkennen, ob sich Objekte wie LKW auf dem Areal befinden. 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

isDemo
bool

Das Mischwerk ist nicht real, sondern existiert lediglich für Demonstrationszwecke.

Mögliche Fehler

Kein Mischwerk mit der angegebenen ID vorhanden

Es exisitiert kein Mischwerk mit der angegebenen ID.

404 - Not found

 

Artikel

Diese Ressource repräsentiert das Artikel-Verzeichnis eines bestimmten Anbieters bzw. eines Mischwerks. Ein Artikel entspricht in der Regel einer verkaufsfähigen Ware.

Eine Artikelübersicht abfragen

GET  https://[BaseUrl]/plants/{plantId}/articles?skip={integer}&take={integer}

GET  https://[BaseUrl]/plants/{plantId}/articles?skip={integer}&take={integer}

Liefert eine Übersichts- oder Auswahlliste der vom Mischwerk angebotenen Artikel.

  • Die Liste umfasst lediglich Artikel, welche in Q Directories als “Für Bestellsystem freigegeben” gekennzeichnet sind.

Query Params

skip
integer
0 <= Wert

Index im Result-Set. Anzahl Datensätze, welche 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
Response Body
{ "pagination": { "offset": 0, "count": 50, "total": 465, "hasMoreEntries": true, }, "items": [ //... ] }

Response Body (articles)

id
UUID
required

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

identifier
string(100)
required

Kennung des Artikels. In der Regel die Artikel-Nummer.

name
string(100)
required

Bezeichnung des Artikels.

articleType
string(100)
required

Grundlegender Typ des Artikels. Hierbei handelt es sich um einen Wert aus der nachfolgenden Aufzählung: ‘asphalt', ‘concrete’, ‘gravel’, '’.

group
string(100)

Artikelgruppe, zu welcher der Artikel gehört.

unit
string(40)
required

Masseinheit, in welcher der Artikel verkauft wird.

price
decimal(10,3)

Listenpreis / Masseinheit ‘unit’

currency
string(20)
conditionally required

Währungs-Kurzzeichen. Pflicht, sobald ein Preis vorliegt.

hasDocuments
bool
required

Zu dem Artikel existieren Dokumente. Dazu zählt auch das Dokument für die Erstprüfung.

 

 

Einzelnen Asphalt-Artikel nach ID abfragen

GET  https://[BaseUrl]/plants/{plantId}/articlesasphalt/{articleId}

GET  https://[BaseUrl]/plants/{plantId}/articlesasphalt/{articleId}

Liefert alle Detailinformationen zu dem adressierten Artikel des Typs ‘asphalt’.

  • Die Methode liefert lediglich Informationen zu Artikel, welche in Q Directories als “Für Bestellsysteme verfügbar” gekennzeichnet sind. Für Artikel mit der Kennzeichnung “Nicht sichtbar“ liefert die Methode den Returncode 404.

Path Params

articleId
UUID
required

Global eindeutige ID (UUID) des abgefragten Mischgutartikels

Response

  • 200 - OK

Response Body (articlesasphalt)

id
UUID
required

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

identifier
string(100)
required

Kennung des Artikels. In der Regel die Artikel-Nummer aus dem ERP.

name
string(100)
required

Bezeichnung des Artikels.

group
string(100)

Artikelgruppe, zu welcher der Artikel gehört.

unit
string(40)
required

Masseinheit, in welcher der Artikel verkauft wird.

price
decimal(10,3)

Listenpreis / Masseinheit ‘unit’

currency
string(20)
conditionally required

Währungs-Kurzzeichen. Pflicht, sobald ein Preis vorliegt.

minPavingTemp
decimal(10,3)

Minimale Einbautemperatur des Mischguts

pavingTempUnit
string(40)
conditionally required

Masseinheit der Einbautemperatur. Pflicht, sobald ein Temperaturwert vorliegt.

minLoadingTemp
decimal(10,3)

Minimale Verladetemperatur des Mischguts auf dem Mischwerk.

maxLoadingTemp
decimal(10,3)

Maximale Verladetemperatur des Mischguts auf dem Mischwerk.

loadingTempUnit
string(40)
conditionally required

Masseinheit der Verladetemperatur. Pflicht, sobald ein Temperaturwert vorliegt.

compactedDensity
decimal(10,3)

Raumdichte des Mischguts

compactedDensityUnit
string(40)
conditionally required

Masseinheit der Raumdichte (in der Regel g/cm3 ). Pflicht, sobald ein Dichtewert vorliegt.

appraisalIdentifier
string(100)

Bezeichnung bzw. Nummer der Eignungsprüfung

appraisalValidityDate
date

Ablaufdatum der Eignungsprüfung.

appraisalDocUrl
string(1000)

URL zum Dokument der Eignungsprüfung. Hierbei handelt es sich um eine sogenannte “Shared Access Signature (SAS)”.

  • Die URL besitzt eine beschränkte Gültigkeitsdauer von wenigen Tagen und darf deshalb clientseitig nicht gespeichert werden.

  • Die Existenz der URL ist der Indikator, ob ein Dokument vorliegt oder nicht.

  • Das Dokument ist per Definition vom MIME-Type "application/pdf”.

appraisalDocFilename
string(300)
conditionally required

Dateiname inklusive Extension der Eignungsprüfung (Beispielsweise: “EP 01-02354-14 Landeck.pdf“). Pflicht, sobald auch eine entsprechende URL 'appraisalDocUrl' vorhanden.

documents
list[document]

Liste von weiteren Dokumenten zum Artikel. In der Regel PDF-Dokumente.

 

Object (document)

mimeType
string(40)
required

MIME Type des Dokuments (Beispielsweise: "application/pdf”).

filename
string(300)
required

Dateiname inklusive Extension (Beispielsweise: “Verwendungshinweise-Art45678.pdf“).

fileUrl
string(1000)
required

URL zum Dokument. Hierbei handelt es sich um eine sogenannte “Shared Access Signature (SAS)”. Die URL besitzt eine beschränkte Gültigkeitsdauer von wenigen Tagen und darf deshalb clientseitig nicht gespeichert werden.

Mögliche Fehler

Kein Artikel mit der angegebenen ID vorhanden

Es existiert kein Artikel mit der angegebenen ID oder dieser in Q Directories als “Nicht sichtbar” gekennzeichnet ist

404 - Not found

 

Adressiertes Mischwerk konnte nicht gefunden werden

Der durch den Path-Parameter adressiertes Mischwerk konnte nicht gefunden werden.

404 - Not Found

Attribute

Value

errorIdentifier

InvalidParameterValue

errorMessage

Plant not found

reason

Plant error