Kurzübersicht
Einführung
Das Vetera Praxis-Management-System kann mit Drittanbieter-Anwendungen mithilfe von Tools namens REST API und Webhooks integriert werden.
Webhooks sind in Vetera verfügbar, um Benachrichtigungen an Drittsysteme über Ergänzungen 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 auf die in der Vetera-Anwendung gespeicherten Daten programmgesteuert zuzugreifen, sie zu bearbeiten oder zu ergänzen – durch jede Drittanbieter-Anwendung. Die REST API von Vetera stellt die meisten der zentralen Vetera-Daten bereit, die von anderen Systemen gelesen oder verändert werden können.
Die Kombination aus Vetera Webhooks & REST API schafft einzigartige Möglichkeiten für den Aufbau integrierter Lösungen. Jeder Anbieter anderer Systeme, der mit diesen Technologien vertraut ist, kann die Daten im Vetera Praxis-Management-System problemlos integrieren, indem er diese Technologien nutzt.
Bevor Sie mit den Vetera APIs starten können, müssen wir Ihnen den Zugriff auf eine Testumgebung aktivieren. Bitte kontaktieren Sie unseren Partner Development Manager, um zu beginnen.
Wir erstellen für Sie eine Testumgebung für den Zugriff während der ersten Entwicklung. Außerdem erstellen wir Ihnen eine Integration-Template mit dem gewünschten OAuth2 grant type, sodass Sie Zugriff auf Ihre Testumgebung haben. Damit können Sie Ihren Code mit unserer API entwickeln und testen.
Sehen Sie sich unsere Developer-Seite an, um API-Dokumentation, API-Schema und weitere wertvolle Informationen zu finden, die Ihre Entwicklung unterstützen.
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 Erstellung von Webhooks per API zu automatisieren. Weitere Informationen zur aktuellen Liste der Webhook Triggers sowie die detaillierte Webhooks guide finden Sie auf unserer Entwicklerseite.
REST API
Vetera stellt die REST API bereit, um den Zugriff auf die in Vetera gespeicherten Daten zu ermöglichen. Die API verwendet OAuth 2.0 authentication. Die Daten werden im JSON-Format zurückgegeben.
Um auf die REST API zuzugreifen, benötigen Sie eine Integration-Template.
Die Vetera API unterstützt zwei grant types: Authorization Code und Client Credentials.
Authorization Code wird für die Authentifizierung von Benutzeroberflächen und in Fällen verwendet, in denen Benutzer selbst auf die API zugreifen. 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 mit einem anderen kommunizieren, ohne dass Benutzeraktionen erforderlich sind.
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 <vetera_id> ist die eindeutige ID der Vetera-Instanz für Ihr Unternehmen
Die gesamte URL wird immer in API Einstellungen in Vetera Einstellungen > Integration > Open API access angezeigt.
Die Vetera REST API ist browsable, was Entwicklern eine gute Möglichkeit bieten sollte, die Möglichkeiten des Datentransfers zu beurteilen.
Add an Integration Application in Vetera
Sobald die Template erstellt ist, ist die Integration im Integration Catalogue in Vetera zu sehen: Einstellungen > Integration > Open API access > Anwendung hinzufügen. Im Catalogue werden die verfügbaren Integrationen aufgelistet und es gibt eine kurze Beschreibung, was jede Integration macht. Falls die Integration weitere Anweisungen zur Einrichtung hat, wird das ebenfalls im Catalogue angezeigt.
Integrationen können eine eingeschränkte Sichtbarkeit haben: Sie können auf bestimmte Vetera Mandanten oder auf bestimmte Länder beschränkt werden. Der Drittanbieter, der die Integration bereitstellt, kann auswählen, wie breit die Integration für die Mandanten sichtbar sein muss. Wenn es Einschränkungen gibt, wird die Anwendung im Integration Catalogue nur bei denjenigen Mandanten / in denjenigen Ländern angezeigt, für die sie erlaubt ist.
Optionen bei einer neuen Client Registration
Jedes Mal, wenn sich ein neuer Kunde zur Nutzung einer Integration anmeldet, also sie im Integration Catalogue in Vetera auswählt (Anwendung hinzufügen), werden eindeutige Client Credentials an den Integration-Provider gesendet. Es gibt zwei Optionen, um eine Registrierung eines neuen Kunden zu benachrichtigen, die beim Erstellen einer Integration-Template ausgewählt werden kann:
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 für die Integration konfigurieren und direkt damit starten. Wenn die Integration hingegen breit eingesetzt wird, werden hookup URL und die Automatisierung des Hinzufügens neuer Kunden empfohlen.
Hookup URL wartet auf automatisierte Benachrichtigungen neuer 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 ausliest und dessen Credentials in ihre Client-Tabelle übernimmt.
JSON schema für die Daten, die für neue Integration Registrations 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": "Signaturalgorithmus, der verwendet wird.", "examples": [null, "HS256", "RS256"] }, "authorization_grant_type": { "type": "string", "description": "Verwendeter Authorization-Flow.", "examples": ["authorization_code", "client_credentials"] }, "client_type": { "type": "string", "description": "Client-Typ.", "examples": ["confidential", "public"] }, "redirect_uris": { "type": "string", "description": "Liste von 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 authorize endpoint 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] } }}Permissions
Wenn eine neue Integration-Anwendung 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 ist in Einstellungen > Benutzer über den Virtuell-Filter zu finden. Die Berechtigungsgruppe hat denselben Namen wie die Integration.
Vetera unterstützt automatisiertes Berechtigungsmanagement, reduziert manuellen Aufwand und sorgt für Konsistenz. Diese Funktion heißt „permission template“ und wird in der Integration-Template ergänzt. Kontaktieren Sie die Vetera Unterstützung, um Ihre permission template in Ihrer Integration-Template zu erhalten.
Wenn permission templates geändert werden, wird die zugehörige Berechtigungsgruppe in Vetera automatisch aktualisiert, um dem neuesten Template zu entsprechen. Die hinzugefügten Berechtigungen werden übernommen, und entfernte Berechtigungen werden ausgeschlossen, um die Synchronisierung sicherzustellen.
Wenn keine permission templates verwendet werden, haben sie standardmäßig dieselben Berechtigungen wie die Berechtigungsgruppe Benutzer.
Wenn eine Integration unterschiedliche Berechtigungen benötigt (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 außerdem View and Manage User Permissions.
Department-Specific Integration
In Vetera Umgebungen mit mehreren Standorten der Klinik kann eine Integration separat für jeden Standort der Klinik aktiviert oder deaktiviert werden. Diese Einstellung ist nur informativ und erstellt keine zusätzlichen Kundendaten. Die Liste der Standorte der Klinik, für die die Integration aktiviert ist, ist im Daten-Payload des Webhooks enthalten.
Jedes Mal, wenn die Integration für einen Standort der Klinik aktiviert oder deaktiviert wird, wird ein neuer Webhook gesendet, der die folgenden Informationen enthält:
Alle derzeit 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 Standorte der Klinik Ihre Integration nutzen oder nicht nutzen, verbinden Sie bitte die Vetera Unterstützung und fragen Sie, ob Sie diese Funktion für Ihre Integration aktiviert bekommen können.
In Vetera zeigen integrations, die standortabhängig sind, am Ende der Zeile eine Aktivieren- oder Deaktivieren-Schaltfläche an. Damit können Nutzer die Integration für den Standort der Klinik aktivieren oder deaktivieren, den sie gerade ansehen. Nachdem eine Integration hinzugefügt wurde, muss sie für jeden Standort der Klinik separat aktiviert werden. Die Standorte der Klinik, für die die Integration aktiviert ist, werden neben der Deaktivieren-Schaltfläche angezeigt. Wenn eine Integration keine standortabhängige 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 die Vetera Unterstützung, damit Ihr Integration-Template für alle Vetera-Instanzen sichtbar ist. Wenn Ihre Integration nicht kundenspezifisch ist und von vielen Nutzern in vielen Vetera-Instanzen genutzt werden soll, müssen vor dem Livegang bestimmte Anforderungen erfüllt sein. Diese Anforderungen sollen das Onboarding der Integration erleichtern und der Vetera Unterstützung die benötigten Informationen 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 ausführen muss, um Ihre Integration in Betrieb zu nehmen. Die Schritte können auch die Aktionen umfassen, die in Ihrem System erforderlich sind.
Sehen Sie sich diese Beispiel-Onboarding-Anleitung an. Das Beispiel verwendet einen Webhook; Ihre Integration benötigt möglicherweise aber andere Konfigurationen, z. B. ein Benutzerdefiniertes Feld usw.
Stellen Sie uns sowohl das Video als auch die Onboarding-Anleitung zur Verfügung 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 die folgenden Funktionen für öffentliche Integrationen, die über viele Vetera Mandanten hinweg genutzt werden:
permission template
Hookup URL statt E-Mail-Benachrichtigung
Erstellung von Webhooks und Benutzerdefinierten Schaltflächen über API-Endpunkte (falls anwendbar)
Wenn Sie diese Funktionen nicht verwenden, kontaktieren Sie bitte die Vetera Unterstützung, damit wir Ihnen für Sie permission template und hookup URL konfigurieren. Wenn Sie einen konkreten Grund haben, eine Benachrichtigungs-E-Mail zu verwenden, geben Sie uns bitte Bescheid.
Für Partner mit standortbasierter Abrechnung ist die standortabhängige Funktion erforderlich. Sie muss konfiguriert, getestet und in die Onboarding-Anweisungen aufgenommen werden, bevor die Integration live gehen kann.