Einführung
Das Vetera-Praxis-Managementsystem kann mithilfe von Tools namens REST API und Webhooks in Anwendungen von Drittanbietern integriert werden.
Webhooks sind in Vetera verfügbar, um Drittanbietern Benachrichtigungen über Ergänzungen oder Änderungen in den Daten innerhalb von Vetera zu senden. Die Webhooks übertragen nicht die tatsächlich geänderten Daten, sondern übermitteln lediglich die Information darüber, was sich geändert hat, indem sie das jeweilige Ereignis an das Drittanbietersystem melden. Die tatsächlichen Daten kann das Drittanbietersystem anschließend über die REST API von Vetera abrufen.
REST API ist eine Kommunikationsmethode, mit der jede Drittanbieter-Anwendung programmgesteuert auf die in Vetera gespeicherten Daten zugreifen, sie bearbeiten oder hinzufügen kann. Die REST API von Vetera macht die meisten zentralen Vetera-Daten für das Auslesen oder die Manipulation durch andere Systeme verfügbar.
Die Kombination aus Vetera Webhooks & REST API schafft einzigartige Möglichkeiten, um integrierte Lösungen aufzubauen. Jeder Anbieter anderer Systeme, der mit diesen Technologien vertraut ist, kann sich mithilfe dieser Technologien problemlos in das Vetera-Praxis-Managementsystem integrieren, das die Daten in Vetera enthält.
Bevor Sie mit den Vetera-APIs starten können, müssen wir für Sie den Zugriff auf eine Testumgebung aktivieren. Bitte kontaktieren Sie unsere Partner Development Manager, um zu beginnen.
Wir erstellen für Sie eine Testumgebung, auf die Sie während der ersten Entwicklung zugreifen können. Außerdem stellen wir Ihnen eine Integrationsvorlage mit dem gewünschten OAuth2 grant type bereit, die Zugriff auf Ihre Testumgebung ermöglicht. So können Sie Ihren Code mit unserer API entwickeln und testen.
Weitere Informationen zu API-Dokumentation, API-Schema und anderen hilfreichen Details finden Sie auf unserer Entwicklerseite.
Webhooks
Webhooks können in Einstellungen > Allgemeines > Integration > Webhooks konfiguriert und aktiviert werden oder über einen API-Endpunkt. Wenn Ihre Integration Webhooks verwendet, empfehlen wir, die Erstellung von Webhooks über eine API zu automatisieren. Weitere Informationen zur aktuellen Liste der Webhook-Triggers sowie die ausführliche Webhooks-Anleitung 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 nutzt OAuth 2.0 authentication. Die Daten werden im JSON-Format zurückgegeben.
Um auf die REST API zuzugreifen, benötigen Sie eine Integrationsvorlage.
Die Vetera API unterstützt zwei grant types: Authorization Code und Client Credentials.
Authorization Code wird für die Authentifizierung von Benutzeroberflächen und für Fälle verwendet, 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, bei der Dienste direkt miteinander kommunizieren, ohne dass Benutzereingriffe erforderlich sind.
Die REST API kann über eine URL abgerufen 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 enthalten
Die gesamte URL wird in den API-Einstellungen in Vetera immer angezeigt unter Einstellungen > Integration > Offener API-Zugang.
Die Vetera REST API ist browsable, sodass Entwickler die Möglichkeiten zum Datentransfer gut prüfen können.
Eine Integrationsanwendung in Vetera hinzufügen
Sobald die Vorlage erstellt ist, ist die Integration im Integrationskatalog in Vetera sichtbar: 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 für die Integration weitere Anweisungen zur Einrichtung vorhanden sind, wird dies ebenfalls im Katalog angezeigt.
Integrationen können eine eingeschränkte Sichtbarkeit haben: Sie können nur für bestimmte Vetera Mandanten oder in bestimmten Ländern verfügbar sein. Der Drittanbieter, der die Integration bereitstellt, kann festlegen, wie weit die Integration auf den Mandanten sichtbar sein soll. Wenn Einschränkungen vorliegen, wird die Anwendung im Integrationskatalog nur in den Mandanten / in den Ländern angezeigt, in denen sie erlaubt ist.
Optionen bei einer neuen Kundenanmeldung
Jedes Mal, wenn sich ein neuer Kunde registriert, um eine Integration zu nutzen, also diese aus dem Integrationskatalog in Vetera auswählt (Anwendung hinzufügen), werden eindeutige Kundenzugangsdaten an den Integrationsanbieter übermittelt. Für die Benachrichtigung über eine Registrierung eines neuen Kunden gibt es zwei Optionen, die beim Erstellen einer Integrationsvorlage 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 für die Integration konfigurieren und sofort damit starten. Wenn die Integration jedoch breit eingesetzt wird, wird empfohlen, stattdessen Hookup URL und das Automatisieren des Hinzufügens eines neuen Kunden zu verwenden.
Hookup URL wartet auf automatisierte Benachrichtigungen über neue Kunden. Wenn ein neuer Kunde die Integration in Vetera hinzufügt, sendet das Orchestrierungs-Tool automatisch eine JSON-Nachricht an die angegebene URL. Es ist keine manuelle Interaktion erforderlich: Die Integration kann den neuen Kunden automatisch aus der JSON-Nachricht auslesen und dessen Zugangsdaten in die Client-Tabelle übernehmen.
JSON-Schema für die Daten, die bei neuen 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 of the tenant who added this integration." }, "client_id": { "type": "string" }, "client_secret": { "type": ["null", "string"] }, "algorithm": { "type": ["null", "string"], "description": "Signing algorithm used.", "examples": [null, "HS256", "RS256"] }, "authorization_grant_type": { "type": "string", "description": "Authorization flow used.", "examples": ["authorization_code", "client_credentials"] }, "client_type": { "type": "string", "description": "Client type.", "examples": ["confidential", "public"] }, "redirect_uris": { "type": "string", "description": "Space-separated list of callback URIs.", "examples": ["https://example.com/callback"] }, "token_url": { "type": "string", "description": "OAuth2.0 token endpoint URL." }, "authorize_url": { "type": "string", "description": "OAuth2.0 authorize endpoint URL." }, "openid_autodiscovery_url": { "type": ["null", "string"], "description": "OpenID autodiscovery URL. Null if integration does not use OpenID." }, "departments": { "type": "array", "items": { "type": "integer" }, "description": "Array of department IDs that have enabled this integration.", "examples": [[1, 2, 3]] }, "added_department": { "type": "integer", "description": "ID of the department that enabled this integration.", "examples": [3] }, "removed_department": { "type": "integer", "description": "ID of the department that disabled this integration.", "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 ist unter Einstellungen > Benutzer über den Filter Virtuell zu finden. Die Berechtigungsgruppe hat denselben Namen wie die Integration.
Vetera unterstützt die automatische Verwaltung von Berechtigungen, reduziert den manuellen Aufwand und sorgt für Konsistenz. Diese Funktion heißt „permission template“ und wird zur Integrationsvorlage hinzugefügt. Kontaktieren Sie den Vetera-Support, damit Sie Ihre permission template in Ihrer Integrationsvorlage erhalten.
Wenn Berechtigungsvorlagen geändert werden, wird die zugehörige Berechtigungsgruppe in Vetera automatisch so aktualisiert, dass sie der neuesten Vorlage entspricht. Die hinzugefügten Berechtigungen werden übernommen, und die entfernten Berechtigungen werden ausgeschlossen, um die Synchronisierung sicherzustellen.
Wenn keine Berechtigungsvorlagen verwendet werden, gelten standardmäßig dieselben Berechtigungen wie für 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 auch View and Manage User Permissions.
Integrationen mit Abteilungsspezifik
In Vetera-Umgebungen mit mehreren Klinikstandorten kann eine Integration unabhängig für jeden Klinikstandort aktiviert oder deaktiviert werden. Diese Einstellung dient nur zur Information und erstellt keine zusätzlichen Kundendaten. Die Liste der Klinikstandorte, für die die Integration aktiviert ist, ist im Daten-Payload des Webhooks enthalten.
Jedes Mal, wenn die Integration für einen Klinikstandort aktiviert oder deaktiviert wird, wird ein neuer Webhook gesendet, der die folgenden Informationen 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, verwenden Sie denselben Vetera-Mandanten, dann kontaktieren Sie den Vetera-Support und fragen Sie, ob diese Funktion für Ihre Integration aktiviert werden kann.
In Vetera zeigen integrations, die standort-spezifisch sind, am Ende der Zeile eine Aktivieren- oder Deaktivieren-Schaltfläche an. Dadurch können Nutzer die Integration für den Klinikstandort aktivieren oder deaktivieren, den sie gerade ansehen. Nach dem Hinzufügen einer Integration muss sie separat für jeden Klinikstandort aktiviert werden. Die Klinikstandorte, für die die Integration aktiviert ist, werden neben der Deaktivieren-Schaltfläche angezeigt. Wenn eine Integration keine Aktivierung mit Klinikstandort-spezifischen Einstellungen unterstützt, wird sie automatisch auf Unternehmensebene aktiviert.
Eine Integration freigeben
Wenn Sie Ihre Integration entwickelt und getestet haben und sie für die öffentliche Nutzung freigeben möchten, kontaktieren Sie den Vetera-Support, damit Ihre Integrationsvorlage für alle Vetera-Instanzen sichtbar wird. Wenn Ihre Integration nicht kundenspezifisch ist und von vielen Nutzern in vielen Vetera-Instanzen verwendet werden soll, müssen vor dem Livegang bestimmte Anforderungen erfüllt sein. Diese Anforderungen sollen das Onboarding der Integration erleichtern und den Vetera-Support mit den erforderlichen Informationen versorgen.
Erstellen Sie ein kurzes Video über Ihre Integration: wie sie genutzt wird und was sie macht.
Erstellen Sie eine Onboarding-Anleitung, die alle manuellen Schritte enthält, die der Vetera-Nutzer 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 diese Beispiel-Onboarding-Anleitung. Das Beispiel nutzt einen Webhook, aber Ihre Integration benötigt möglicherweise weitere Konfigurationen, z. B. ein benutzerdefiniertes Feld etc.
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 für öffentliche Integrationen, die in vielen Vetera-Mandanten verwendet werden, die folgenden Funktionen:
permission template
Hookup URL statt E-Mail-Benachrichtigung
Erstellung von Webhooks und benutzerdefinierten Schaltflächen über API-Endpunkte (falls zutreffend)
Wenn Sie diese Funktionen nicht verwenden, kontaktieren Sie bitte den Vetera-Support, damit wir für Sie permission template und Hookup URL konfigurieren. Wenn Sie einen spezifischen Grund haben, eine Benachrichtigungs-E-Mail zu verwenden, informieren Sie uns bitte.
Für Partner mit standortbezogenem Rechnungswesen ist die standort-spezifische Funktion erforderlich. Sie muss konfiguriert, getestet und in die Onboarding-Anleitungen aufgenommen werden, bevor die Integration live gehen kann.