Introducción
El sistema de gestión de consultas veterinarias Provet se puede integrar con aplicaciones de terceros mediante herramientas denominadas API REST y webhooks.
Webhooks están disponibles en Provet para enviar notificaciones a sistemas de terceros sobre las adiciones o cambios en los datos dentro de Provet. Los webhooks no transfieren los datos modificados en sí, sino que envían la información sobre qué ha cambiado, notificando simplemente al sistema de terceros el cambio. A continuación, el sistema de terceros puede recuperar los datos reales mediante la API REST de Provet.
REST API es un método de comunicación para acceder, editar o añadir datos que residen en el programa Provet de forma programática por cualquier aplicación de terceros. La REST API de Provet ofrece la mayoría de los datos clave de Provet para que puedan leerse o manipularse por otros sistemas.
La combinación de webhooks de Provet y REST API crea posibilidades únicas para construir soluciones integradas. Cualquier proveedor de otros sistemas que conozca estas tecnologías puede integrar fácilmente los datos que residen en el sistema de gestión de consultas veterinarias Provet utilizando estas tecnologías.
Antes de que puedas empezar a utilizar las APIs de Provet, necesitamos habilitar el acceso al entorno de pruebas. Ponte en contacto con nuestro Partner Development Manager para comenzar.
Creamos un entorno de pruebas para que puedas acceder durante el desarrollo inicial. También crearemos para ti una plantilla de integración con el tipo de concesión OAuth2 deseado, con acceso a tu entorno de pruebas. Esto te permitirá desarrollar y probar tu código con nuestra API.
Consulta nuestra página para desarrolladores para ver la documentación de la API, el esquema de la API y otra información útil que te ayudará con tu desarrollo.
Webhooks
Los webhooks se pueden configurar y habilitar en Ajustes > Integraciones > Webhooks, o mediante un endpoint de API. Si tu integración utiliza webhooks, recomendamos automatizar la creación de webhooks mediante una API. Consulta nuestro sitio de desarrolladores para ver el Listado de desencadenadores de webhooks actualizado y la guía de Webhooks detallada.
REST API
Provet proporciona la REST API para habilitar el acceso a los datos almacenados en Provet. La API usa autenticación OAuth 2.0. Los datos se devuelven en formato JSON.
Para acceder a la REST API necesitas una plantilla de integración.
La API de Provet admite dos tipos de concesión: Authorization Code y Client Credentials.
Authorization Code se utiliza para autenticar interfaces de usuario y casos en los que los usuarios acceden a la API como ellos mismos. PKCE se admite y se recomienda encarecidamente. Los clientes públicos DEBEN usar PKCE.
Client Credentials se utiliza para la conectividad del backend, donde los servicios se comunican directamente con otro sin ninguna acción del usuario.
La REST API se puede acceder usando una URL que se compila de la siguiente manera: https://<provet_environment>/<provet_id>/api/0.1/
La URL <provet_environment> es un poco diferente para cada entorno. Puede ser, por ejemplo
provetcloud.com para el entorno de la UE
us.provetcloud.com para el entorno de EE. UU.
En la URL <provet_id> está el ID único de la instancia de Provet para tu empresa
Toda la URL se muestra siempre en los Ajustes de Provet Settings > Integrations > Open API access.
La REST API de Provet es navegable, lo que debería permitir una buena posibilidad para que los desarrolladores evalúen las posibilidades de transferencia de datos.
Añadir una Aplicación de Integración en Provet
Una vez creada la plantilla, la integración se puede ver en el catálogo de integraciones en Provet: Ajustes > Integraciones > Acceso abierto a la API > Añadir aplicación. El catálogo muestra las integraciones disponibles y ofrece una breve descripción de lo que hace cada integración. Si la integración tiene más instrucciones de configuración, también se muestran en el catálogo.
Las integraciones pueden tener visibilidad restringida: se pueden restringir a únicamente ciertos tenants de Provet o a determinados países. El tercero que proporciona la integración puede elegir qué tan ampliamente necesita mostrarse la integración en los tenants. Cuando hay restricciones, la aplicación se muestra en el catálogo de integraciones solo en aquellos tenants / países en los que esté permitido.
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 en el catálogo de integraciones de Provet (Añadir aplicación), se envían credenciales de cliente únicas al proveedor de la integración. Hay dos opciones para notificar un registro de un nuevo cliente que se pueden elegir al crear una plantilla de integración:
correo electrónico
hookup URL
Cuando la integración se usa solo en una instancia de Provet, el correo electrónico es una buena opción: así, la persona que recibe el correo electrónico puede configurar los detalles de autenticación de la integración y empezar a utilizarla. Por otro lado, cuando la integración se usa ampliamente, se recomienda hookup URL y la automatización para añadir 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 la URL indicada. No es necesario ningún tipo de interacción humana, ya que la integración analiza automáticamente el nuevo cliente a partir del mensaje JSON y añade sus credenciales a su tabla de clientes.
Esquema JSON para los datos enviados para 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 en Provet, se crea automáticamente un usuario virtual y un grupo de permisos para la integración. El usuario virtual se llama Integration <Integration name> y se puede encontrar en Ajustes > Usuarios usando el filtro Virtual. El grupo de permisos tiene el mismo nombre que la integración.
Provet admite la gestión automatizada de permisos, lo que reduce el trabajo manual y garantiza la coherencia. Esta función se llama «plantilla de permisos» y se añade en la plantilla de integración. Contacta con el soporte técnico de Provet para obtener tu plantilla de permisos en tu 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 plantilla más reciente. Se incluyen los permisos añadidos y se excluyen los permisos eliminados para garantizar la sincronización.
Si no se utiliza una plantilla de permisos, tiene los mismos permisos por defecto que el grupo de permisos Usuarios.
Si una integración requiere permisos diferentes (algunos endpoints están denegados o quieres restringir los permisos), los permisos deben editarse. Consulta en el esquema de API de Provet qué permisos necesita cada endpoint. Consulta también Ver y gestionar permisos de usuario.
Integración específica por Ubicación de la clínica
En entornos de Provet con varias ubicaciones de clínicas, una integración se puede habilitar o deshabilitar por separado para cada ubicación de la clínica. Este ajuste es solo informativo y no crea datos adicionales de cliente. La lista de ubicaciones de clínicas donde la integración está habilitada se incluye en la carga de datos del webhook.
Cada vez que se habilita o deshabilita la integración para una ubicación de clínica, se envía un nuevo webhook que contiene la siguiente información:
Todos los departamentos actualmente habilitados
El departamento que se añadió
El departamento que se eliminó
Esta funcionalidad normalmente no es necesaria. Si necesitas tener información sobre qué ubicaciones de clínicas usan o no usan tu integración en el mismo tenant de Provet, ponte en contacto con el soporte técnico de Provet y pregunta si puedes tener esta función habilitada para tu integración.
En Provet, las integraciones que son específicas de ubicación de clínica muestran un botón Habilitar o Deshabilitar al final de la fila. Esto permite a los usuarios habilitar o deshabilitar la integración para la ubicación de la clínica que están visualizando en ese momento. Después de añadir una integración, debe habilitarse por separado para cada ubicación de clínica. Las ubicaciones de clínicas donde la integración está habilitada se muestran junto al botón Deshabilitar. Si una integración no admite activación específica por ubicación de clínica, se activa automáticamente a nivel de organización.
Publicar una integración
Cuando hayas desarrollado y probado tu integración y quieras publicarla para uso público, contacta con el soporte técnico de Provet para que tu Plantilla de integración sea visible para todas las instancias de Provet. Si tu integración no es específica para clientes y está pensada para usarse en muchas instancias de Provet por muchos usuarios, hay algunos requisitos que deben cumplirse antes de pasar a producción. Estos requisitos pretenden facilitar el proceso de incorporación de la integración y proporcionar la información necesaria para el soporte técnico de Provet.
Crea un vídeo breve sobre tu integración: cómo se utiliza y qué hace.
Crea una instrucción de incorporación que contenga todos los pasos manuales necesarios que debe realizar el usuario de Provet para poner tu integración en funcionamiento. Los pasos pueden incluir las acciones necesarias en tu sistema.
Consulta esta guía de ejemplo de incorporación. El ejemplo de integración usa un webhook, pero tu integración puede necesitar otra configuración, como un campo personalizable, etc.
Envíanos tanto el vídeo como la guía de incorporación e infórmanos en qué mercados / países debería ser visible tu integración.
Para automatizar la incorporación y minimizar el error humano, recomendamos utilizar las siguientes funciones para integraciones públicas que se utilicen en muchos tenants de Provet:
Plantilla de permisos
Hookup URL en lugar de notificación por correo electrónico
Creación de webhooks y botones personalizados mediante endpoints de API (si aplica)
Si no tienes estas funciones en uso, ponte en contacto con el soporte técnico de Provet para configurar la plantilla de permisos y el hookup URL para ti. Si tienes una razón específica para utilizar una notificación por correo electrónico, indícanoslo.
Para partners con facturación basada en la ubicación, es necesaria 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 publicarse.