Kurzübersicht
Einführung
Das Vetera Praxis-Managementsystem kann mit Drittanbieteranwendungen mithilfe von Tools integriert werden, die als REST API und Webhooks bezeichnet werden.
Webhooks sind in Vetera verfügbar, um Benachrichtigungen an Drittsysteme über Hinzufügungen oder Änderungen in den Daten innerhalb von Vetera zu senden. Die Webhooks übertragen nicht die tatsächlich geänderten Daten, sondern stattdessen die Information darüber, was sich geändert hat, indem sie das Drittsystem lediglich über die Änderung informieren. Die tatsächlichen Daten können anschließend vom Drittsystem über die REST API von Vetera abgerufen werden.
REST API ist eine Kommunikationsmethode, um die Daten in Vetera programmgesteuert über jede Drittanbieteranwendung abzurufen, zu bearbeiten oder hinzuzufügen. Die REST API von Vetera stellt die meisten der wichtigsten Vetera-Daten bereit, die von anderen Systemen gelesen oder bearbeitet werden können.
Die Kombination aus Vetera Webhooks und REST API eröffnet einzigartige Möglichkeiten, integrierte Lösungen zu erstellen. Jeder Anbieter anderer Systeme, der mit diesen Technologien vertraut ist, kann die Daten in dem Vetera Praxis-Managementsystem problemlos integrieren, indem er diese Technologien nutzt.
Bevor Sie mit den Vetera API anfangen können, müssen wir den Zugriff auf eine Testumgebung für Sie aktivieren. Bitte kontaktieren Sie unseren Partner Development Manager, um zu starten.
Wir erstellen eine Testumgebung für Sie, die Sie während der ersten Entwicklung nutzen können. Außerdem erstellen wir Ihnen eine Integration-Vorlage mit dem gewünschten OAuth2 Grant-Typ, die einen Zugriff auf Ihre Testumgebung ermöglicht. So können Sie Ihren Code mit unserer API entwickeln und testen.
Weitere Informationen finden Sie auf unserer Entwicklerseite für API-Dokumentation, API-Schema und andere wertvolle Informationen, die Ihnen bei der Entwicklung helfen.
Webhooks
Webhooks können konfiguriert und aktiviert werden in Einstellungen > Allgemeines > Integration > Webhooks oder über einen API-Endpunkt. Wenn Ihre Integration Webhooks verwendet, empfehlen wir, die Webhook-Erstellung per API zu automatisieren. Sehen Sie auf unserer Entwicklerseite die aktuelle Liste der Webhook-Triggers sowie die detaillierte Webhooks-Anleitung.
REST API
Vetera stellt die REST API bereit, um den Zugriff auf die in Vetera gespeicherten Daten zu ermöglichen. Die API nutzt OAuth 2.0-Authentifizierung. Die Daten werden im JSON-Format zurückgegeben.
Um auf die REST API zuzugreifen, benötigen Sie eine Integration-Vorlage.
Die Vetera API unterstützt zwei Grant-Typen: Authorization Code und Client Credentials.
Authorization Code wird zur Authentifizierung von Benutzeroberflächen verwendet und für Fälle, in denen Benutzer die API als sie selbst aufrufen. PKCE wird unterstützt und dringend empfohlen. Öffentliche Clients MÜSSEN PKCE verwenden.
Client Credentials wird für die Backend-Konnektivität verwendet, wenn Services direkt ohne Benutzeraktionen mit einem anderen Dienst kommunizieren.
Die REST API kann über eine URL aufgerufen werden, die wie folgt zusammengesetzt ist: https://<vetera_environment>/<vetera_id>/api/0.1/
In der URL ist <vetera_id> die eindeutige ID der Vetera-Instanz für Ihr Unternehmen
Die gesamte URL wird in API Einstellungen in Vetera Einstellungen > Integration > Offener API-Zugang immer angezeigt.
Die Vetera REST API ist browsable, was Entwicklern ermöglichen sollte, die Möglichkeiten des Datentransfers gut zu beurteilen.
Eine Integrationsanwendung in Vetera hinzufügen
Sobald die Vorlage erstellt ist, kann die Integration im Integrationskatalog in Vetera angezeigt werden: Einstellungen > Integration > Offener API-Zugang > Anwendung hinzufügen. Der Katalog listet die verfügbaren Integrationen auf und enthält eine kurze Beschreibung, was jede Integration macht. Wenn die Integration weitere Einrichtungsanweisungen hat, wird dies ebenfalls im Katalog angezeigt.
Integrationen können eine eingeschränkte Sichtbarkeit haben: Sie können auf bestimmte Vetera Mandanten oder in bestimmten Ländern beschränkt werden. Der Drittanbieter, der die Integration bereitstellt, kann auswählen, wie breit die Integration für Mandanten sichtbar sein muss. Wenn Einschränkungen bestehen, wird die Anwendung nur in dem Integrationskatalog für die Mandanten / in den Ländern angezeigt, in denen sie zulässig ist.
Optionen bei neuer Kunde-Registrierung
Jedes Mal, wenn sich ein neuer Kunde registriert, um eine Integration zu nutzen, d. h. er sie aus dem Integrationskatalog in Vetera auswählt (Anwendung hinzufügen), werden einzigartige Kundenzugangsangaben an den Integrationsanbieter übermittelt. Es gibt zwei Optionen, um eine Registrierung eines neuen Kunden zu benachrichtigen, die beim Erstellen einer Integration-Vorlage ausgewählt werden können:
E-Mail
Hookup URL
Wenn die Integration nur auf einer Vetera-Instanz verwendet wird, ist E-Mail eine gute Wahl: Dann kann die Person, die die E-Mail erhält, die Authentifizierungsdetails in der Integration konfigurieren und sofort damit starten. Wenn die Integration hingegen breit genutzt wird, wird empfohlen, Hookup URL und die Automatisierung des Hinzufügens eines neuen Kunden zu verwenden.
Hookup URL lauscht auf alle automatisierten Benachrichtigungen über neue Kunden. Wenn ein neuer Kunde die Integration in Vetera hinzufügt, sendet das Orchestrierungstool automatisch eine JSON-Nachricht an die angegebene URL. Es ist keine manuelle Interaktion erforderlich, wenn die Integration den neuen Kunden automatisch aus der JSON-Nachricht verarbeitet und dessen Zugangsdaten in dessen Kunde-Tabelle hinzufügt.
JSON-Schema für die Daten, die für neue Integrationsregistrierungen gesendet werden:
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "Vetera_id", "client_id", "client_secret", "algorithm", "authorization_grant_type", "client_type", "redirect_uris", "token_url", "authorize_url", "openid_autodiscovery_url" ], "properties": { "Vetera_id": { "type": "number", "description": "Vetera ID des Mandanten, der diese Integration hinzugefügt hat." }, "client_id": { "type": "string" }, "client_secret": { "type": ["null", "string"] }, "algorithm": { "type": ["null", "string"], "description": "Verwendetes Signieralgorithmus.", "examples": [null, "HS256", "RS256"] }, "authorization_grant_type": { "type": "string", "description": "Verwendeter Autorisierungsablauf.", "examples": ["authorization_code", "client_credentials"] }, "client_type": { "type": "string", "description": "Client-Typ.", "examples": ["confidential", "public"] }, "redirect_uris": { "type": "string", "description": "Liste der Callback-URIs, durch Leerzeichen getrennt.", "examples": ["https://example.com/callback"] }, "token_url": { "type": "string", "description": "OAuth2.0 Token-Endpunkt-URL." }, "authorize_url": { "type": "string", "description": "OAuth2.0 Autorisierungs-Endpunkt-URL." }, "openid_autodiscovery_url": { "type": ["null", "string"], "description": "OpenID Autodiscovery-URL. Null, wenn die Integration OpenID nicht verwendet." }, "departments": { "type": "array", "items": { "type": "integer" }, "description": "Array von Abteilungs-IDs, für die diese Integration aktiviert wurde.", "examples": [[1, 2, 3]] }, "added_department": { "type": "integer", "description": "ID der Abteilung, die diese Integration aktiviert hat.", "examples": [3] }, "removed_department": { "type": "integer", "description": "ID der Abteilung, die diese Integration deaktiviert hat.", "examples": [3] } }}Berechtigungen
Wenn eine neue Integrationsanwendung zu Vetera hinzugefügt wird, werden automatisch ein virtueller Benutzer und eine Berechtigungsgruppe für die Integration erstellt. Der virtuelle Benutzer heißt Integration <Integration name> und kann in Einstellungen > Benutzer über den Filter Virtuell gefunden werden. Die Berechtigungsgruppe hat denselben Namen wie die Integration.
Vetera unterstützt die automatisierte Verwaltung von Berechtigungen, wodurch der manuelle Aufwand reduziert und die Konsistenz sichergestellt wird. Diese Funktion heißt „permission template“ und wird zur Integration-Vorlage hinzugefügt. Kontaktieren Sie Vetera Unterstützung, damit wir Ihnen die Berechtigungs-Vorlage in Ihrer Integration-Vorlage bereitstellen.
Wenn Berechtigungs-Vorlagen geändert werden, wird die zugehörige Berechtigungsgruppe in Vetera automatisch aktualisiert, um der neuesten Vorlage zu entsprechen. Die hinzugefügten Berechtigungen werden aufgenommen und die entfernten Berechtigungen werden ausgeschlossen, um die Synchronisierung sicherzustellen.
Wenn keine Berechtigungs-Vorlagen verwendet werden, haben sie standardmäßig dieselben Berechtigungen wie die Berechtigungsgruppe Benutzer.
Wenn eine Integration unterschiedliche Berechtigungen erfordert (einige Endpunkte sind verweigert oder Sie möchten die Berechtigungen einschränken), müssen die Berechtigungen bearbeitet werden. Prüfen Sie in der Vetera API schema, welche Berechtigungen jeder Endpunkt benötigt. Siehe auch Benutzerberechtigungen anzeigen und verwalten.
Abteilungsspezifische Integration
In Vetera Umgebungen mit mehreren Klinikstandorten kann eine Integration separat für jeden Klinikstandort aktiviert oder deaktiviert werden. Diese Einstellung ist nur informativ und erstellt keine zusätzlichen Kundendaten. Die Liste der Klinikstandorte, für die die Integration aktiviert ist, ist in der Daten-Nutzlast des Webhooks enthalten.
Jedes Mal, wenn die Integration für einen Klinikstandort aktiviert oder deaktiviert wird, wird ein neuer Webhook gesendet, der die folgende Information enthält:
Alle aktuell aktivierten Abteilungen
Die Abteilung, die hinzugefügt wurde
Die Abteilung, die entfernt wurde
Diese Funktion wird normalerweise nicht benötigt. Wenn Sie wissen müssen, welche Klinikstandorte Ihre Integration verwenden oder nicht verwenden, auf demselben Vetera Mandanten, kontaktieren Sie bitte Vetera Unterstützung und fragen Sie, ob diese Funktion für Ihre Integration aktiviert werden kann.
In Vetera zeigen integrations, die klinikstandort-spezifisch sind, am Ende der Zeile eine Schaltfläche Aktivieren oder Deaktivieren an. So können Nutzer die Integration für den Klinikstandort aktivieren oder deaktivieren, den sie gerade ansehen. Nachdem eine Integration hinzugefügt wurde, muss sie separat für jeden Klinikstandort aktiviert werden. Die Klinikstandorte, für die die Integration aktiviert ist, werden neben der Schaltfläche Deaktivieren angezeigt. Wenn eine Integration keine klinikstandort-spezifische Aktivierung unterstützt, wird sie automatisch auf Organisationsebene aktiviert.
Eine Integration freigeben
Wenn Sie Ihre Integration entwickelt und getestet haben und sie für die öffentliche Nutzung freigeben möchten, kontaktieren Sie Vetera Unterstützung, damit wir Ihre Integration-Vorlage für alle Vetera Instanzen sichtbar machen. Wenn Ihre Integration nicht kundenspezifisch ist und für viele Vetera Instanzen durch viele Benutzer verwendet werden soll, müssen vor dem Livegang einige Anforderungen erfüllt werden. Diese Anforderungen sollen das Onboarding der Integration erleichtern und den benötigten Informationsumfang für die Vetera Unterstützung bereitstellen.
Erstellen Sie ein kurzes Video über Ihre Integration: wie man sie nutzt und was sie macht.
Erstellen Sie eine Onboarding-Anleitung, die alle manuellen Schritte enthält, die der Vetera Benutzer benötigt, um Ihre Integration in Betrieb zu nehmen. Die Schritte können auch die Aktionen beinhalten, die in Ihrem System erforderlich sind.
Sehen Sie sich dieses Beispiel für eine Onboarding-Anleitung an. Das Beispiel für eine Integration verwendet einen Webhook, aber Ihre Integration benötigt möglicherweise eine andere Konfiguration, z. B. ein benutzerdefiniertes Feld usw.
Stellen Sie uns sowohl das Video als auch die Onboarding-Anleitung bereit und teilen Sie uns mit, in welchen Märkten / in welchen Ländern Ihre Integration sichtbar sein soll.
Um das Onboarding zu automatisieren und menschliche Fehler zu minimieren, empfehlen wir, für öffentliche Integrationen, die in vielen Vetera Mandanten verwendet werden, die folgenden Funktionen zu nutzen:
Berechtigungs-Vorlage
Hookup URL statt E-Mail-Benachrichtigung
Erstellung von Webhooks und benutzerdefinierten Schaltflächen über API-Endpunkte (falls zutreffend)
Wenn Sie diese Funktionen nicht nutzen, kontaktieren Sie bitte Vetera Unterstützung, damit wir Ihnen die Berechtigungs-Vorlage und die Hookup URL konfigurieren. Wenn Sie einen konkreten Grund haben, eine Benachrichtigungs-E-Mail zu verwenden, lassen Sie es uns bitte wissen.
Für Partner mit standortbasierter Abrechnung ist die klinikstandort-spezifische Funktion erforderlich. Sie muss konfiguriert, getestet und in die Onboarding-Anweisungen aufgenommen werden, bevor die Integration live gehen kann.