Wofür du die Crownbeam-API nutzt
Über die Crownbeam-API greifen andere Programme direkt auf die Daten deines Labors zu, ohne dass jemand in Crownbeam klickt. Labore nutzen die API zum Beispiel, um ihre eigene Abrechnungssoftware anzubinden oder um Auswertungen zu ihrer Produktion zu erstellen.
Über die API kannst du unter anderem diese Daten abrufen:
Aufträge
Auftragspositionen
Produkte
Kunden
Standorte
Die Daten übernimmst du in ein Werkzeug deiner Wahl, zum Beispiel Excel oder Power BI. Die eigentliche Anbindung setzt in der Regel ein Entwickler um. In Crownbeam brauchst du dafür einen API-Benutzer mit passenden Berechtigungen, wie unten beschrieben.
Was ist ein API-Benutzer
Ein API-Benutzer ist ein eigener System-Benutzer, über den externe Systeme auf die Crownbeam-API zugreifen. Für den API-Zugriff brauchst du zwingend einen solchen API-Benutzer, ein persönlicher Account genügt dafür nicht. Du legst diesen Benutzer selbst an und gibst ihm gezielt die Berechtigungen, die das angebundene System wirklich braucht.
Du findest den Bereich unter Einstellungen → Meine Daten → API Verwaltung.
Hinweis: Die API Verwaltung ist als Beta gekennzeichnet. Einige Unterseiten und Buttons werden noch auf Englisch angezeigt. In dieser Anleitung stehen die englischen Bezeichnungen jeweils in Klammern.
So legst du einen API-Benutzer an
Öffne die Einstellungen über das Zahnrad-Symbol oben rechts.
Wähle unter Meine Daten den Menüpunkt API Verwaltung.
Klicke im Bereich API-Benutzer (API Users) auf API Benutzer verwalten.
Klicke oben rechts auf Systembenutzer erstellen (Create Systemuser).
Trage einen Namen (Name) ein und halte in der Beschreibung (Description) fest, wofür der Benutzer verwendet wird.
Wähle unter Sprache (Language) die gewünschte Sprache aus.
Klicke auf Erstellen.
Tipp: Lege pro angebundenem System einen eigenen API-Benutzer an und benenne ihn danach. So siehst du in der Liste sofort, welcher Zugang wozu gehört, und kannst einzelne Anbindungen getrennt voneinander abschalten.
Welche Berechtigungen es gibt
Die verfügbaren Berechtigungen siehst du in der API Verwaltung über den Button Verfügbare Berechtigungen. Crownbeam ermittelt diese Liste automatisch aus den vorhandenen API-Endpunkten.
Die Berechtigungen sind nach Datenbereich gruppiert, zum Beispiel Aufträge (Order), Dateien (Files), Nachrichten (Message) und Standorte (Location). Pro Bereich gibt es vier Aktionen:
Aktion | Was sie erlaubt |
Hinzufügen (ADD) | Neue Einträge anlegen |
Ändern (CHANGE) | Bestehende Einträge bearbeiten |
Löschen (DELETE) | Einträge löschen |
Ansehen (VIEW) | Einträge lesen |
Zu jeder Berechtigung stehen der Name, der technische Codename wie view_order und eine ID. Diese Angaben braucht in der Regel nur der Entwickler, der die Anbindung umsetzt.
Wichtig: Gib einem API-Benutzer nur die Berechtigungen, die das angebundene System wirklich benötigt. Ein Benutzer, der Daten nur ausliest, braucht kein Löschen.
Die Rechte deines Teams sind davon getrennt. Sie werden weiterhin unter Einstellungen → Mein Unternehmen → Team vergeben, wie in Benutzerrechte verwalten beschrieben.
Welche APIs zur Verfügung stehen
Crownbeam stellt drei REST-APIs zur Verfügung. Welche davon du brauchst, hängt davon ab, aus welcher Perspektive das externe System arbeitet:
API | Wofür |
Admin API | (Aktuell ohne Funktionen !) |
Lab API | Zugriff aus Sicht des Labors |
Practice API | Zugriff aus Sicht der Praxis |
Die Übersicht öffnest du in der API Verwaltung über API-Portal öffnen (Visit API Portal). Zu jeder API findest du dort die Dokumentation, das Schema und eine Swagger-Oberfläche zum Testen sowie die unterstützten Authentifizierungsmethoden.
Hinweis: Brauchst du Unterstützung bei der Umsetzung einer Integration, wende dich an [email protected].
Was über die Lab API derzeit nicht möglich ist
Die Lab API deckt nicht alles ab, was du in der Weboberfläche von Crownbeam machen kannst. Derzeit gelten diese Einschränkungen:
Inbox: Scans aus DS Core, Medit oder 3Shape Communicate, die noch in der Inbox liegen, sind noch keine Aufträge und erscheinen nicht in der API. Erst wenn du den Scan in der Inbox einer Praxis zuordnest und annimmst, ist er über die API abrufbar. Die Inbox selbst lässt sich über die API nicht lesen und Scans lassen sich darüber nicht annehmen.
Die Positionen eines Auftrags lassen sich über die API nicht ändern. Preis und Lieferzeit berechnet Crownbeam aus der Preisliste und den Auftragseinstellungen.
Crownbeam meldet neue Aufträge oder Statusänderungen nicht von selbst an deine Software, es gibt keine Webhooks. Deine Software fragt die Daten stattdessen regelmäßig ab.
Hinweis: Technische Details wie Abfragelimits, Filter und Seitengrößen findest du in der API-Dokumentation im API-Portal.
FAQs
Kann ich einen API-Benutzer selbst anlegen?
Du kannst einen API-Benutzer selbst anlegen. Der Weg dafür ist Einstellungen → Meine Daten → API Verwaltung → API Benutzer verwalten und dort Systembenutzer erstellen (Create Systemuser). Du musst dafür keine Anfrage an den Support stellen.
Warum brauche ich für die API einen eigenen Benutzer?
Für die API ist ein eigener Benutzer verpflichtend, damit der technische Zugriff getrennt von persönlichen Accounts läuft. So kannst du die Berechtigungen gezielt auf das angebundene System zuschneiden und den Zugang abschalten, ohne einen Mitarbeiter-Account zu verändern.
Wo finde ich die API-Dokumentation?
Die API-Dokumentation liegt im API-Portal. Du erreichst es über Einstellungen → Meine Daten → API Verwaltung und den Button API-Portal öffnen (Visit API Portal).
Kann ich Auswertungen oder Berichte zu meiner Produktion erstellen?
Crownbeam bietet im Portal keine Auswertungen oder Berichte zur Produktion, zum Beispiel zu produzierten Einheiten pro Monat nach Arbeitsart, Material oder Praxis. Diese Zahlen holst du dir über die API: Du rufst Aufträge, Auftragspositionen, Produkte, Kunden und Standorte ab und wertest sie in einem Werkzeug deiner Wahl aus. Das geht auch rückwirkend für vergangene Monate. Berichte von Hand erstellt das Crownbeam-Team nicht.
Benachrichtigt Crownbeam meine Software über neue Aufträge?
Crownbeam benachrichtigt deine Software derzeit nicht aktiv über neue Aufträge oder Statusänderungen, es gibt keine Webhooks. Deine Software fragt die Daten stattdessen regelmäßig über die API ab. Für die meisten Fälle reicht ein Abstand von 5 Minuten. Pro API-Benutzer sind bis zu 120 Anfragen pro Minute möglich.
Warum sehe ich Scanner-Aufträge nicht über die API?
Scanner-Aufträge aus DS Core, Medit oder 3Shape Communicate erscheinen erst in der API, wenn aus dem Scan ein Auftrag geworden ist. Solange ein Scan in der Inbox liegt, ordnest du ihn dort einer Praxis zu und nimmst ihn an. Aktivierst du dabei die Checkbox Zukünftig automatisch zuordnen, werden spätere Scans desselben Absenders sofort als Auftrag angelegt und sind direkt über die API abrufbar.
Gibt es einen Testzugang für die API?
Für die Entwicklung einer Anbindung stellt Crownbeam auf Anfrage einen Test-Account bereit. Wende dich dafür an den Crownbeam-Support und nenne eine E-Mail-Adresse, die mit dem Test-Account verbunden werden soll. Diese Adresse darf in Crownbeam noch nicht verwendet werden.