Enlaces rápidos
Introducción
El sistema de gestión de consultas veterinarias Provet puede integrarse con aplicaciones de terceros mediante herramientas denominadas REST API y webhooks.
Webhooks están disponibles en Provet para enviar notificaciones a sistemas de terceros sobre adiciones o cambios en los datos dentro de Provet. Los webhooks no transfieren los datos reales modificados, sino que transfieren la información sobre lo que ha cambiado simplemente notificando el cambio al sistema de terceros. Los datos reales pueden ser obtenidos por el sistema de terceros mediante la utilización de la API REST de Provet.
REST API es un método de comunicación para acceder, editar o añadir a los datos que residen en Provet de forma programática por cualquier aplicación de terceros. La API REST de Provet ofrece la mayoría de los datos clave de Provet para ser leídos o manipulados por otros sistemas.
La combinación de Provet webhooks & REST API crea posibilidades únicas para la construcción de soluciones integradas. Cualquier proveedor de otros sistemas familiarizado con estas tecnologías puede integrarse fácilmente con los datos que residen en el sistema de gestión de la práctica veterinaria Provet utilizando estas tecnologías.
Antes de que pueda empezar a utilizar las APIs de Provet, necesitamos habilitarle el acceso al entorno de pruebas. Por favor, póngase en contacto con nuestro Partner Development Manager para empezar.
Crearemos un entorno de prueba para que pueda acceder durante el desarrollo inicial. También le crearemos una plantilla de integración con el tipo de concesión OAuth2 deseado para que tenga acceso a su entorno de prueba. Esto le permitirá desarrollar y probar su código con nuestra API.
Visite nuestra página para desarrolladores para consultar la documentación de la API, el esquema de la API y otra información valiosa que le ayudará en su desarrollo.
Webhooks
Los webhooks pueden configurarse y activarse en Configuración > General > Integraciones > Webhooks, o a través de un punto final de API. Si su integración utiliza webhooks, le recomendamos automatizar la creación de webhooks a través de una API. Consulte nuestro sitio para desarrolladores para obtener la lista actualizada de desencadenadores de webhooks y la guía detallada Webhooks.
API REST
Provet proporciona la API REST para permitir el acceso a los datos almacenados en Provet. La API utiliza autenticación OAuth 2.0. Los datos se devuelven en el formato JSON.
Para acceder a la API REST necesita una plantilla de integración.
La API de Provet admite dos tipos de concesión: Código de Autorización y Credenciales de Cliente.
El Código de Autorización se utiliza para autenticar interfaces de usuario y casos en los que los usuarios acceden a la API como ellos mismos. PKCE es compatible y muy recomendable. Los clientes públicos DEBEN usar PKCE.
Las credenciales de cliente se utilizan para la conectividad backend en la que los servicios se comunican directamente con otros sin ninguna acción del usuario.
Se puede acceder a la API REST utilizando una URL compilada como sigue: https://<provet_environment>/<provet_id>/api/0.1/
<provet_environment> La URL difiere un poco para cada entorno. Puede ser, por ejemplo
provetcloud.com para el medio ambiente de la UE
us.provetcloud.com para el entorno estadounidense
En la URL <provet_id> es el ID único de la instancia Provet para su empresa
La URL completa se muestra siempre en la configuración de la API en Provet Configuración > Integraciones > Acceso a la API abierta.
Provet REST API es navegable, lo que debería permitir a los desarrolladores evaluar las posibilidades de transferencia de datos.
Añadir una aplicación de integración en Provet
Una vez creada la plantilla, la integración puede verse en el catálogo de integraciones en Provet: Configuración > Integraciones > Abrir acceso API > Añadir aplicación. El catálogo enumera las integraciones disponibles y tiene una breve descripción de lo que hace cada integración. Si la integración tiene más instrucciones de configuración, que se muestra en el catálogo también.
Las integraciones pueden tener una visibilidad restringida: pueden estar restringidas sólo a determinados inquilinos de Provet o en determinados países. La tercera parte que proporciona la integración puede elegir hasta qué punto la integración debe ser visible en los inquilinos. Cuando hay restricciones, la aplicación se muestra en el Catálogo de Integración sólo en aquellos inquilinos / en aquellos países en los que está permitida.
Opciones en el registro de un nuevo cliente
Cada vez que un nuevo cliente se registra para utilizar una integración, es decir, la elige del catálogo de integraciones en Provet (Añadir Aplicación), se envían credenciales únicas de cliente al proveedor de la integración. Hay dos opciones para notificar el registro de un nuevo cliente que se pueden elegir al crear una plantilla de integración:
correo electrónico
URL de conexión
Cuando la integración se utiliza sólo en una instancia de Provet, el correo electrónico es una buena opción: entonces la persona que recibe el correo electrónico puede configurar los detalles de autenticación a la integración y empezar a usarlo. Por otro lado, cuando la integración se utiliza ampliamente, se recomienda la URL de conexión y automatizar la adición de un nuevo cliente.
Hookup URL está a la escucha de cualquier notificación automatizada de nuevos clientes. Cuando un nuevo cliente añade la integración en Provet, la herramienta de orquestación envía automáticamente un mensaje JSON a esa URL dada. No hay necesidad de ninguna interacción humana, cuando la integración analiza automáticamente el nuevo cliente desde el mensaje JSON y añade sus credenciales a su tabla de clientes.
Esquema JSON de los datos enviados para los nuevos registros de integración:
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "provet_id", "client_id", "client_secret", "algorithm", "authorization_grant_type", "client_type", "redirect_uris", "token_url", "authorize_url", "openid_autodiscovery_url" ], "properties": { "provet_id": { "type": "number", "description": "Provet 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] } }}Permisos
Cuando se añade una nueva aplicación de integración a Provet, se crean automáticamente un usuario virtual y un grupo de permisos para la integración. El usuario virtual se llama Integración <Nombre de la integración> y se puede encontrar en Configuración > Usuarios utilizando el filtro Virtual. El grupo de permisos tiene el mismo nombre que la integración.
Provet soporta la gestión automatizada de permisos, reduciendo el esfuerzo manual y garantizando la coherencia. Esta característica se llama 'plantilla de permisos' y se añade en la plantilla de integración. Póngase en contacto con el soporte de Provet para obtener su plantilla de permisos en su plantilla de integración.
Cuando se modifican las plantillas de permisos, el grupo de permisos asociado en Provet se actualiza automáticamente para que coincida con la última plantilla. Los permisos añadidos se incluyen, y los permisos eliminados se excluyen para garantizar la sincronización.
Si no se utiliza una plantilla de permisos, tendrá por defecto los mismos permisos que el grupo de permisos Usuarios.
Si una integración requiere permisos diferentes (algunos endpoints están denegados o desea restringir los permisos), los permisos deben ser editados. Compruebe en el esquema Provet API qué permisos necesita cada endpoint. Véase también Ver y administrar permisos de usuario.
Integración por departamentos
En entornos Provet con múltiples ubicaciones clínicas, se puede activar o desactivar una integración por separado para cada ubicación clínica. Esta configuración es sólo informativa y no crea ningún dato adicional del cliente. La lista de clínicas donde la integración está habilitada se incluye en la carga de datos del webhook.
Cada vez que se activa o desactiva la integración para la ubicación de una clínica, se envía un nuevo webhook con la siguiente información:
Todos los departamentos habilitados actualmente
El departamento que se añadió
El departamento suprimido
Esta funcionalidad normalmente no es necesaria. Si necesita tener la información sobre qué clínicas utilizan o no su integración en el mismo inquilino Provet, por favor, póngase en contacto con el soporte de Provet y pregunte si puede tener esta función habilitada para su integración.
En Provet, las integraciones que son específicas de la ubicación de la clínica muestran un botón Activar o Desactivar al final de la fila. Esto permite a los usuarios activar o desactivar la integración para la ubicación de la clínica que están viendo actualmente. Una vez añadida la integración, debe habilitarse por separado para cada centro de salud. Las clínicas en las que está activada la integración se muestran junto al botón Disable. Si una integración no admite la activación específica de una ubicación clínica, se activa automáticamente a nivel de organización.
Liberar una integración
Cuando haya desarrollado y probado su integración y desee lanzarla al uso público, póngase en contacto con el soporte de Provet para que su Plantilla de Integración sea visible para todas las instancias de Provet. Si su integración no es específica del cliente y está destinada a ser utilizada en muchas instancias de Provet por muchos usuarios, hay algunos requisitos que deben cumplirse antes de ir en vivo. Estos requisitos están destinados a facilitar la integración y proporcionar la información necesaria para el soporte de Provet.
Cree un breve vídeo sobre su integración: cómo utilizarla y qué hace.
Cree una instrucción de incorporación que contenga todos los pasos manuales necesarios para que el usuario de Provet pueda utilizar su integración. Los pasos también pueden incluir las acciones necesarias en su sistema.
Consulte este ejemplo de guía de integración. El ejemplo de integración utiliza un webhook, pero su integración podría necesitar alguna otra configuración como un campo personalizado, etc.
Facilítenos tanto el vídeo como la guía de incorporación y díganos en qué mercados/países debería ser visible su integración.
Para automatizar la integración y minimizar el error humano, recomendamos utilizar las siguientes características para las integraciones públicas que se utilizan en muchos inquilinos de Provet:
Plantilla de permisos
URL de conexión en lugar de notificación por correo electrónico
Creación de webhooks y botones personalizados mediante puntos finales de API (si procede)
Si no tiene estas características en uso, por favor contacte con el soporte de Provet para configurar la plantilla de permisos y la URL de conexión para usted. Si usted tiene una razón específica para utilizar un correo electrónico de notificación, por favor háganoslo saber.
Para los socios con facturación basada en la ubicación, se requiere la función específica de ubicación de la clínica. Debe configurarse, probarse e incluirse en las instrucciones de incorporación antes de que la integración pueda ponerse en marcha.