Ligações rápidas
Introdução
O sistema de gestão de clínicas veterinárias Provet pode ser integrado com aplicações de terceiros utilizando ferramentas denominadas REST API e webhooks.
Webhooks estão disponíveis em Provet para enviar notificações a sistemas de terceiros sobre adições ou alterações nos dados dentro de Provet. Os webhooks não transferem os dados efetivamente alterados, mas transferem a informação sobre o que foi alterado, notificando simplesmente o sistema de terceiros sobre a alteração. Os dados efectivos podem então ser obtidos pelo sistema de terceiros utilizando a API REST de Provet.
REST API é um método de comunicação que permite a qualquer aplicação de terceiros aceder, editar ou adicionar dados residentes na Provet de forma programática. A API REST do Provet permite que a maior parte dos principais dados do Provet sejam lidos ou manipulados por outros sistemas.
A combinação dos webhooks da Provet & REST API cria possibilidades únicas para a criação de soluções integradas. Qualquer fornecedor de outros sistemas familiarizado com estas tecnologias pode facilmente integrar-se com os dados que residem no sistema de gestão de clínicas veterinárias Provet, utilizando estas tecnologias.
Antes de poder começar a utilizar as APIs da Provet, é necessário ativar o acesso ao ambiente de teste. Contacte o nosso Partner Development Manager para começar.
Criaremos um ambiente de teste ao qual poderá aceder durante o desenvolvimento inicial. Também criaremos um modelo de integração com o tipo de concessão OAuth2 pretendido para que tenha acesso ao seu ambiente de teste. Isto permitir-lhe-á desenvolver e testar o seu código com a nossa API.
Consulte a nossa página de programador para obter a documentação da API, o esquema da API e outras informações valiosas para o ajudar no seu desenvolvimento.
Webhooks
Os webhooks podem ser configurados e activados em Definições > Geral > Integrações > Webhooks, ou através de um ponto de extremidade da API. Se a sua integração utilizar webhooks, recomendamos que automatize a criação de webhooks através de uma API. Consulte o nosso site de programadores para obter a lista actualizada de Webhook Triggers e o guia detalhado Webhooks.
API REST
O Provet fornece a API REST para permitir o acesso aos dados armazenados no Provet. A API utiliza a autenticação OAuth 2.0. Os dados são devolvidos no formato JSON.
Para aceder à API REST é necessário um modelo de integração.
A API do Provet suporta dois tipos de concessão: Código de autorização e Credenciais de cliente.
O Código de Autorização é utilizado para autenticar interfaces de utilizador e casos em que os utilizadores acedem à API como se fossem eles próprios. O PKCE é suportado e altamente recomendado. Os clientes públicos DEVEM utilizar o PKCE.
As credenciais de cliente são utilizadas para a conetividade de backend, em que os serviços comunicam diretamente com outros sem quaisquer acções do utilizador.
A API REST pode ser acedida através de um URL compilado da seguinte forma: https://<provet_environment>/<provet_id>/api/0.1/
<provet_environment> O URL difere um pouco para cada ambiente. Pode ser, por exemplo
provetcloud.com para o ambiente da UE
us.provetcloud.com para o ambiente dos EUA
No URL <provet_id> é o ID único da instância Provet para a sua empresa
O URL completo é sempre apresentado nas definições da API em Provet Definições > Integrações > Acesso à API aberta.
A API REST do Provet é navegável, o que deve permitir aos programadores avaliar as possibilidades de transferência de dados.
Adicionar uma aplicação de integração em Provet
Uma vez criado o modelo, a integração pode ser vista no catálogo de integrações do Provet: Definições > Integrações > Acesso à API aberta > Adicionar aplicação. O catálogo lista as integrações disponíveis e apresenta uma breve descrição do que cada integração faz. Se a integração tiver mais instruções de configuração, estas também são apresentadas no catálogo.
As integrações podem ter uma visibilidade restrita: podem ser limitadas a apenas alguns lojistas Provet ou em determinados países. O terceiro que fornece a integração pode escolher em que medida a integração deve ser visível nos locatários. Quando existem restrições, a aplicação é apresentada no Catálogo de integração apenas nos locatários/países em que é permitida.
Opções no registo de um novo cliente
Sempre que um novo cliente se regista para utilizar uma integração, ou seja, escolhe-a no catálogo de integração em Provet (Adicionar aplicação), são enviadas credenciais de cliente únicas para o fornecedor da integração. Existem duas opções para notificar o registo de um novo cliente que podem ser escolhidas ao criar um modelo de integração:
correio eletrónico
URL de engate
Quando a integração é utilizada apenas numa instância do Provet, o e-mail é uma boa escolha: a pessoa que recebe o e-mail pode configurar os detalhes de autenticação para a integração e começar a utilizá-la. Por outro lado, quando a integração é amplamente utilizada, recomenda-se a utilização do URL de ligação e a automatização da adição de um novo cliente.
O URL de ligação está à escuta de quaisquer notificações automáticas de novos clientes. Quando um novo cliente adiciona a integração no Provet, a ferramenta de orquestração envia automaticamente uma mensagem JSON para esse URL. Não é necessária qualquer interação humana, uma vez que a integração analisa automaticamente o novo cliente a partir da mensagem JSON e adiciona as suas credenciais à sua tabela de clientes.
Esquema JSON para os 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, são automaticamente criados um utilizador virtual e um grupo de permissões para a integração. O utilizador virtual chama-se Integração <Nome da integração> e pode ser encontrado em Definições > Utilizadores utilizando o filtro Virtual. O grupo de permissões tem o mesmo nome que a integração.
O Provet suporta a gestão automatizada de permissões, reduzindo o esforço manual e garantindo a coerência. Esta funcionalidade chama-se "modelo de autorização" e é adicionada ao modelo de integração. Contacte o apoio Provet para obter o seu modelo de permissão no seu modelo de integração.
Quando os modelos de permissão são modificados, o grupo de permissão associado no Provet é automaticamente atualizado para corresponder ao modelo 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 modelo de permissão não for utilizado, tem as mesmas permissões por defeito que o grupo de permissões Users.
Se uma integração exigir permissões diferentes (alguns pontos finais são recusados ou pretende restringir as permissões), as permissões devem ser editadas. Verifique no esquema da API Provet quais as permissões necessárias para cada ponto final. Ver também Ver e gerir as permissões do utilizador.
Integração específica do departamento
Em ambientes Provet com várias localizações de clínicas, uma integração pode ser activada ou desactivada separadamente para cada localização de clínica. Esta definição é apenas informativa e não cria quaisquer dados adicionais do cliente. A lista de localizações de clínicas onde a integração está activada está incluída na carga de dados do webhook.
Sempre que a integração é activada ou desactivada para uma localização clínica, é enviado um novo webhook com as seguintes informações:
Todos os departamentos atualmente activados
O departamento que foi acrescentado
O serviço que foi retirado
Normalmente, esta funcionalidade não é necessária. Se precisar de ter informações sobre quais as clínicas que utilizam ou não a sua integração no mesmo inquilino Provet, contacte o apoio Provet e pergunte se pode ativar esta funcionalidade para a sua integração.
No Provet, as integrações que são específicas da localização da clínica apresentam um botão Ativar ou Desativar no final da linha. Isto permite aos utilizadores ativar ou desativar a integração para a localização da clínica que estão a visualizar atualmente. Depois de uma integração ser adicionada, tem de ser activada separadamente para cada localização clínica. As localizações das clínicas onde a integração está activada são apresentadas junto ao botão Disable (Desativar ). Se uma integração não suportar a ativação específica da localização da clínica, é activada automaticamente ao nível da organização.
Liberação de uma integração
Quando tiver desenvolvido e testado a sua integração e pretender disponibilizá-la ao público, contacte o apoio Provet para tornar o seu modelo de integração visível para todas as instâncias Provet. Se a sua integração não for específica de um cliente e se destinar a ser utilizada em muitas instâncias Provet por muitos utilizadores, existem alguns requisitos que devem ser cumpridos antes de ser lançada. Estes requisitos destinam-se a facilitar a integração e a fornecer as informações necessárias ao apoio do Provet.
Crie um pequeno vídeo sobre a sua integração: como utilizá-la e o que faz.
Crie uma instrução de integração que contenha todos os passos manuais necessários para que o utilizador do Provet possa utilizar a sua integração. Os passos podem incluir também as acções necessárias no seu sistema.
Consulte este exemplo de guia de integração. O exemplo de integração utiliza um webhook, mas a sua integração pode necessitar de outra configuração, como um campo personalizado, etc.
Forneça-nos o vídeo e o guia de integração e diga-nos em que mercados/países deve a sua integração ser visível.
Para automatizar a integração e minimizar erros humanos, recomendamos o uso das seguintes features para integrações públicas que são usadas em muitos locatários da Provet:
Modelo de autorização
URL de ligação em vez de notificação por correio eletrónico
Criação de webhooks e botões personalizados através de pontos de extremidade da API (se aplicável)
Se não estiver a utilizar estas funcionalidades, contacte a assistência Provet para configurar o modelo de permissão e o URL de ligação para si. Se tiver uma razão específica para utilizar um e-mail de notificação, informe-nos.
Para parceiros com faturação baseada na localização, é necessária a funcionalidade específica de localização da clínica. Esta deve ser configurada, testada e incluída nas instruções de integração antes de a integração poder ser activada.