Introdução
O sistema de Gestão de Práticas veterinárias Provet pode ser integrado com aplicações de terceiros utilizando ferramentas chamadas REST API e webhooks.
Webhooks estão disponíveis no Provet para enviar notificações a sistemas de terceiros sobre adições ou alterações nos dados dentro do Provet. Os webhooks não transferem os dados efetivamente alterados; em vez disso, transferem a informação sobre o que foi alterado, notificando simplesmente o sistema de terceiros sobre a alteração. Os dados reais podem, depois, ser obtidos pelo sistema de terceiros através da REST API do Provet.
REST API é um método de comunicação para aceder, editar ou adicionar dados do programa Provet de forma programática por qualquer aplicação de terceiros. A REST API do Provet disponibiliza grande parte dos dados-chave do Provet para serem lidos ou manipulados por outros sistemas.
A combinação de webhooks do Provet e REST API cria possibilidades únicas para desenvolver soluções integradas. Qualquer fornecedor de outros sistemas familiarizado com estas tecnologias consegue integrar facilmente os dados do sistema de Gestão de Práticas veterinárias Provet, utilizando essas tecnologias.
Antes de começar a utilizar as APIs do Provet, precisamos de ativar o acesso ao ambiente de teste para si. Contacte o nosso Partner Development Manager para iniciar.
Criamos um ambiente de teste para si aceder durante o desenvolvimento inicial. Também criamos um modelo de integração com o tipo de concessão OAuth2 pretendido, com acesso ao seu ambiente de teste. Isto permite-lhe desenvolver e testar o seu código com a nossa API.
Veja a nossa página de programadores para documentação da API, schema da API e outras informações úteis para apoiar o seu desenvolvimento.
Webhooks
Os webhooks podem ser configurados e ativados em Settings > Integrations > Webhooks, ou via um endpoint de API. Se a sua integração utilizar webhooks, recomendamos automatizar a criação dos webhooks via API. Consulte o nosso site de programadores para a lista List of Webhook Triggers atualizada e o guia Webhooks guide detalhado.
REST API
O Provet fornece a REST API para permitir o acesso aos dados armazenados no Provet. A API utiliza autenticação OAuth 2.0. Os dados são devolvidos no formato JSON.
Para aceder à REST API, precisa de um modelo de integração.
O suporte da API do Provet oferece dois tipos de grant: Authorization Code e Client Credentials.
Authorization Code é utilizado para autenticar interfaces de utilizador e casos em que os utilizadores acedem à API como eles próprios. PKCE é suportado e altamente recomendado. Os clientes públicos MUST use PKCE.
Client Credentials é usado para conectividade backend, em que os serviços comunicam diretamente com outro sem quaisquer ações por parte do utilizador.
A REST API pode ser acedida usando uma URL compilada da seguinte forma: https://<provet_environment>/<provet_id>/api/0.1/
A URL <provet_environment> difere um pouco em cada ambiente. Pode ser, por exemplo
provetcloud.com para o ambiente da UE
us.provetcloud.com para o ambiente dos EUA
Na URL <provet_id> encontra-se o ID único da instância do Provet da sua empresa
Toda a URL é sempre apresentada em Definições de API no Provet Settings > Integrations > Open API access.
A REST API do Provet é navegável, o que deve permitir uma boa oportunidade para os programadores avaliarem as possibilidades de transferência de dados.
Adicionar uma Aplicação de Integração no Provet
Assim que o modelo for criado, a integração fica visível no catálogo de integrações no Provet: Settings > Integrations > Open API access > Add Application. O catálogo lista as integrações disponíveis e inclui uma breve descrição do que faz cada integração. Se a integração tiver mais instruções de configuração, isso também é mostrado no catálogo.
As integrações podem ter visibilidade restrita: podem ser restringidas a apenas certos clientes Provet (tenants) ou em determinados países. O terceiro que fornece a integração pode escolher o quão amplamente a integração precisa de estar visível nos tenants. Quando há restrições, a aplicação só é mostrada no catálogo de integrações nos tenants / nos países onde é permitido.
Opções no registo de um Novo cliente
Sempre que um novo cliente se regista para utilizar uma integração, ou seja, a escolhe no catálogo de integrações do Provet (Add Application), são enviadas credenciais de cliente exclusivas ao fornecedor da integração. Existem duas opções para notificar um registo de um novo cliente, que podem ser escolhidas ao criar um modelo de integração:
email
hookup URL
Quando a integração é utilizada apenas numa instância do Provet, o email é uma boa escolha: nesse caso, a pessoa que recebe o email pode configurar os detalhes de autenticação da integração e começar a utilizá-la. Por outro lado, quando a integração é utilizada amplamente, recomenda-se o hookup URL e a automação da adição de um novo cliente.
O hookup URL fica à escuta de quaisquer notificações automatizadas sobre novos clientes. Quando um novo cliente adiciona a integração no Provet, a ferramenta de orquestração envia automaticamente uma mensagem JSON para o URL indicado. Não há necessidade de qualquer interação humana: quando a integração analisa automaticamente o novo cliente a partir da mensagem JSON e adiciona as respetivas credenciais na tabela do cliente.
Schema JSON dos dados enviados para novos registos de integração:
{ "$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] } }}
Permissões
Quando uma nova aplicação de integração é adicionada ao Provet, um utilizador virtual e um grupo de permissão são criados automaticamente para a integração. O utilizador virtual é chamado Integration <Integration name> e pode ser encontrado em Settings > Users usando o filtro Virtual. O grupo de permissão tem o mesmo nome da integração.
O Provet suporta gestão automatizada de permissões, reduzindo o esforço manual e garantindo consistência. Esta funcionalidade chama-se 'permission template' e é adicionada no modelo de integração. Contacte o apoio Provet para obter o seu permission template no seu modelo de integração.
Quando os permission templates são modificados, o grupo de permissões associado no Provet é atualizado automaticamente para corresponder ao template mais recente. As permissões adicionadas são incluídas e as permissões removidas são excluídas para garantir a sincronização.
Se um permission template não for utilizado, tem por predefinição as mesmas permissões do grupo de permissão Users.
Se uma integração exigir permissões diferentes (alguns endpoints são recusados ou pretende restringir as permissões), as permissões devem ser editadas. Verifique no Provet API schema quais permissões cada endpoint necessita. Consulte também View and Manage User Permissions.
Integração específica por localização da clínica
Em ambientes do Provet com várias localizações de clínicas, uma integração pode ser ativada ou desativada separadamente para cada localização da clínica. Esta definição é apenas informativa e não cria quaisquer dados adicionais do cliente. A lista das localizações das clínicas em que a integração está ativada é incluída no payload de dados do webhook.
Sempre que a integração é ativada ou desativada para uma localização de clínica, é enviado um novo webhook contendo a seguinte informação:
Todos os departamentos atualmente ativados
O departamento que foi adicionado
O departamento que foi removido
Esta funcionalidade normalmente não é necessária. Se precisar de ter a informação sobre quais localizações das clínicas utilizam ou não utilizam a sua integração no mesmo tenant do Provet, contacte o apoio Provet e pergunte se pode ter esta funcionalidade ativada para a sua integração.
No Provet, as integrações específicas por localização da clínica exibem um botão Enable ou Disable no fim da linha. Isto permite aos utilizadores ativar ou desativar a integração para a localização da clínica que estão a visualizar. Após adicionar uma integração, esta deve ser ativada separadamente para cada localização da clínica. As localizações das clínicas em que a integração está ativada são apresentadas ao lado do botão Disable. Se uma integração não suportar ativação específica por localização da clínica, é ativada automaticamente a nível da organização.
Publicar uma integração
Quando tiver desenvolvido e testado a sua integração e quiser publicá-la para utilização pública, contacte o apoio Provet para disponibilizar o seu Integration Template para todas as instâncias do Provet. Se a sua integração não for específica do cliente e se destinar a ser utilizada em muitas instâncias do Provet por muitos utilizadores, existem alguns requisitos a cumprir antes de avançar para produção. Estes requisitos destinam-se a tornar o onboarding da integração mais fácil e a fornecer as informações necessárias ao apoio Provet.
Crie um vídeo curto sobre a sua integração: como utilizá-la e o que faz.
Crie uma instrução de onboarding que contenha todas as etapas manuais necessárias para o utilizador Provet levar a integração para uso. As etapas podem incluir as ações necessárias no seu sistema também.
Veja este exemplo de guia de onboarding. O exemplo de integração usa um webhook, mas a sua integração pode precisar de alguma outra configuração, como um campo personalizado, etc.
Forneça-nos o vídeo e o guia de onboarding e informe-nos em que mercados / em que países a sua integração deve ficar visível.
Para automatizar o onboarding e minimizar erros humanos, recomendamos usar as seguintes funcionalidades para integrações públicas utilizadas em muitos tenants do Provet:
permission template
Hookup URL em vez de notificação por email
Criação de webhooks e botões personalizados via endpoints de API (se aplicável)
Se não tiver estas funcionalidades em uso, contacte o apoio Provet para configurar o permission template e o hookup URL para si. Se tiver uma razão específica para utilizar um email de notificação, por favor avise-nos.
Para parceiros com faturação baseada na localização, a funcionalidade específica por localização da clínica é necessária. Tem de ser configurada, testada e incluída nas instruções de onboarding antes de a integração poder avançar para produção.