Einführung

Die PlantX API ist eine REST-Schnittstelle zum Sytem Q Plant, über die 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, die 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 Infomation an Ihre eigene Schnittstelle.

• Mischgutbestellung wurde 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. Die technische Dokumentation dazu finden Sie auf der angehängten Referenzseite.

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 evtl. 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.