As integrações personalizadas são uma funcionalidade da Provet Cloud que permite enviar pedidos a recursos externos a partir da Provet Cloud. Para ter acesso a estas funcionalidades, contacte o suporte Provet Cloud.
As integrações personalizadas são geridas em Definições → Integrações → Integrações personalizadas.
Para adicionar uma integração, utilize o botão azul "+Adicionar"; utilize o botão de caneta branco na linha da tabela para editar uma integração.
-
Nome - Especifica a etiqueta do botão visível na interface do utilizador.
-
Página visível - Especifica em que página o botão é visível. Cada integração personalizada só pode ser visível numa página, mas a mesma configuração pode ser duplicada para várias integrações personalizadas.
-
Ação - Especifica a ação que será executada quando se clica no botão.
-
Enviar pedido HTTP - Um pedido é programado em segundo plano e enviado através dos servidores da Provet Cloud. Os utilizadores não verão a página Web, mas poderão ver uma notificação quando o envio estiver a decorrer. O pedido virá dos endereços IP de saída da Provet Cloud, pelo que o ponto de receção deve estar aberto a pedidos externos.
-
Abrir numa nova janela - O URL de destino é aberto numa nova janela/aba do navegador.
-
Abrir no painel lateral - O URL de destino é incorporado na Provet Cloud abrindo um painel lateral no topo do conteúdo da página e apresentando a página como um iframe. O URL de destino deve suportar a incorporação (ou seja, o cabeçalho
X-Frame-Optionsdeve ser definido corretamente).
-
-
Método HTTP - Especifica se o pedido será enviado como um pedido GET, com a carga útil a ser fornecida como parâmetros na cadeia de consulta, ou como um pedido POST, com a carga útil a ser fornecida como dados do formulário.
-
URL - O URL de destino, completo com o esquema.
-
Nome do parâmetro - Nome do parâmetro utilizado quando se fornece o ID do objeto atual.
-
Ativado - Permite ativar e desativar uma integração personalizada. As integrações personalizadas também podem ser eliminadas se já não forem necessárias.
-
Adicionar hash de verificação - Ativa um hash de verificação no payload que pode ser utilizado para verificar se o pedido provém da integração personalizada.
-
Sal de verificação - Um segredo partilhado que é utilizado para calcular o hash de verificação, apenas necessário quando o hash de verificação está ativado.
É possível adicionar um prefixo personalizado ao valor do parâmetro, especificando o nome do parâmetro de forma diferente. Normalmente, especificar o nome do parâmetro como 'id' resultaria em uma solicitação como https://example.com/?id=1. No entanto, se um prefixo personalizado for necessário na frente do valor de ID real, o nome do parâmetro poderá ser definido, por exemplo, como 'id=client_", que enviará uma solicitação https://example.com/?id=client_1.
Os pedidos em segundo plano ("Enviar pedido HTTP") também podem receber valores arbitrários e estáticos que serão adicionados aos pedidos sempre que forem enviados. Isto pode, por exemplo, ser utilizado para incluir cabeçalhos de autorização nos pedidos.
Esta funcionalidade não está implementada para pedidos em primeiro plano ("Abrir numa nova janela", "Abrir no painel lateral"). Os cabeçalhos enviados também não são registados.
Os pedidos enviados em segundo plano ('Enviar pedido HTTP') serão registados num registo interno para efeitos de verificação e auditoria. Isto permite aos administradores verificar que tipo de pedidos foram enviados por quem e a que horas e inspecionar o tipo de resposta que a integração personalizada enviou.
O registo da integração personalizada pode ser visualizado em Definições → Integrações → Integrações personalizadas → Registo.
A vista de registo listará todos os pedidos efectuados, começando pelo pedido mais recente. As informações básicas sobre os pedidos são apresentadas na lista e é possível aceder a mais informações na vista detalhada, clicando no botão de olho no lado direito de cada linha.
O registo não é efectuado em pedidos de primeiro plano ("Abrir numa nova janela", "Abrir no painel lateral"), uma vez que o navegador é responsável por fazer estes pedidos.
Uma vez adicionadas, as integrações personalizadas serão apresentadas como botões nas suas páginas de destino. Os botões de integração personalizados podem ser facilmente distinguidos dos botões da Provet Cloud pelo seu aspeto castanho único.
Se apenas uma integração personalizada estiver configurada para uma página, esta será apresentada como um botão normal, com o nome da integração personalizada utilizado como rótulo. Veja o botão castanho "Ativar integração personalizada" na imagem abaixo (página do cliente).
Se uma página tiver várias integrações personalizadas associadas, as integrações personalizadas serão apresentadas como um menu pendente, utilizando novamente o mesmo aspeto castanho para as distinguir. As entradas do menu utilizarão o nome da integração personalizada como rótulo, tal como os botões singulares. Veja a imagem abaixo para uma ilustração.
As integrações personalizadas não enviam informações detalhadas sobre a página atualmente visível. Em vez disso, enviam apenas o ID do objeto relevante (ID do cliente, ID do paciente, ID da fatura, etc.) que pode ser consultado a partir da API REST da Provet Cloud, à semelhança do funcionamento dos webhooks.
As integrações personalizadas não incluem automaticamente informações sobre a página em que estão registadas. Os utilizadores devem utilizar pontos de extremidade de URL diferentes para páginas diferentes (por exemplo, integration.com/client/ para a integração personalizada da página do cliente e integration.com/patient/ para a integração personalizada da página do paciente) ou, se tal não for possível, nomes de parâmetros diferentes (por exemplo, patient_id para a integração da página do paciente e client_id para a integração da página do cliente, se ambos utilizarem o mesmo URL) e, em seguida, distinguir no lado da integração qual o parâmetro incluído no pedido. Para pedidos em segundo plano, também podem ser utilizados cabeçalhos personalizados.
Também não existe qualquer referência ao ID Provet ativo. Se estiver a criar uma integração partilhada entre várias instâncias de Provet Cloud, recomenda-se que adicione endpoints para cada Provet ID (por exemplo, integration.com/1234/client/ e integration.com/4321/client/ se a integração for utilizada por ambas as instâncias de Provet Cloud 1234 e 4321). Neste caso, recomenda-se também a utilização de hashes de verificação para garantir que os dados são provenientes da instância correta, mesmo que exista uma configuração incorrecta com um URL de integração personalizado. Para pedidos em segundo plano, podem também ser utilizados cabeçalhos personalizados.
Se uma integração personalizada for definida como uma ação "Enviar pedido HTTP", ao clicar no botão de integração personalizada será agendado um pedido para ser enviado em segundo plano utilizando os servidores de trabalho da Provet Cloud. O envio será efectuado de forma assíncrona e, embora normalmente o pedido seja feito quase de imediato, pode haver um atraso em função da quantidade de trabalho atualmente nos servidores. O pedido terá origem nos endereços IP de saída da Provet Cloud.
Quando o pedido estiver a ser agendado, o utilizador verá uma notificação de informação na parte superior da página.
Se o pedido for tratado e concluído sem que o utilizador saia da página, pode ser-lhe mostrada uma notificação adicional após a conclusão da tarefa.
É apresentada uma notificação de sucesso se o pedido for enviado com êxito e a integração responder com um código de estado HTTP de sucesso (entre 200 e 299, inclusive).
No entanto, se o pedido falhar por qualquer motivo, será apresentada uma notificação de erro a vermelho com a indicação "Pedido de integração falhou", com uma mensagem de erro mais específica entre parêntesis.
As mensagens de erro possíveis neste momento são:
-
Erro de backend - Ocorreu um erro desconhecido nos servidores de trabalho da Provet Cloud quando o pedido estava a ser enviado. Pode tratar-se de um erro nos servidores da Provet Cloud. Contacte o suporte da Provet Cloud para obter mais informações.
-
Erro de ligação - O pedido de agendamento do envio efectuado aos servidores da Provet Cloud não foi aceite. Pode ser um erro na ligação do utilizador ou talvez um problema nos servidores da Provet Cloud.
-
Erro de dados - O pedido de agendamento do envio efectuado aos servidores da Provet Cloud continha dados inválidos. Isto sugere um problema na Provet Cloud.
-
Erro de integração - O pedido foi enviado com êxito, mas a integração respondeu com um código de estado HTTP sem êxito (inferior a 200 ou superior a 299). O registo de integração personalizado pode ser utilizado para determinar o motivo se a falha for inesperada.
Se uma integração personalizada for definida como uma ação "Abrir numa nova janela", ao clicar no botão de integração personalizada, o URL de destino será aberto numa nova janela ou, mais frequentemente nos navegadores modernos, num novo separador. A página original de Provet Cloud permanecerá aberta na sua janela/aba original.
Se for utilizado um método de pedido GET, os utilizadores podem ver as informações do payload apresentadas na barra de endereços do browser. Se os utilizadores não puderem ver facilmente as informações do payload transmitidas, considere a utilização de um pedido POST.
Se uma integração personalizada for definida como uma ação "Abrir no painel lateral", clicar no botão de integração personalizada vai buscar o URL de destino dentro do browser e apresenta-o dentro de um elemento iframe dentro de um painel lateral que se abre no topo da página atual.
O URL de destino deve suportar a incorporação através do seu cabeçalho X-Frame-Options.
As integrações personalizadas do cliente serão apresentadas na página do cliente, no lado direito, acima da secção Notas, ao navegar em qualquer um dos separadores do cliente ("Detalhes do cliente", "Faturação", "Tratamentos", etc.). Não será apresentado nos separadores dos pacientes. O ID do cliente será enviado como parâmetro.
Da mesma forma, as integrações personalizadas do paciente serão apresentadas na página do paciente, no lado direito, acima da secção Notas, quando se navega em qualquer separador do paciente ("Detalhes do paciente", "Histórico", "Medidas", etc.). Não será apresentado nos separadores do cliente. O ID do paciente será enviado como parâmetro.
As integrações personalizadas de facturas serão apresentadas nas páginas de facturas (incluindo contra-venda) na barra de ferramentas inferior. O ID da fatura (não confundir com o número da fatura) será enviado como parâmetro.
As integrações personalizadas de consultas serão apresentadas na página da consulta, acima da secção de informações gerais, tanto para consultas em curso como para consultas concluídas. O ID da consulta será enviado como parâmetro.
As integrações personalizadas do calendário de marcações serão apresentadas por cima do calendário de marcações. O ID da localização da clínica ativa será enviado como parâmetro.
Da mesma forma, as integrações personalizadas do calendário de turnos serão apresentadas no topo do calendário de turnos, sob a seleção do tipo de turno e do modelo de turno. O ID da localização da clínica ativa será enviado como parâmetro.
As integrações personalizadas de diagnóstico por imagem serão apresentadas na página de referência de diagnóstico por imagem nas barras de ferramentas superior e inferior. A ID de referência de diagnóstico por imagem será enviada como parâmetro.
As integrações personalizadas de lembretes serão apresentadas na barra de ferramentas de seleção na página de lembretes quando um ou mais lembretes forem selecionados na tabela. Podem ser selecionados e enviados vários lembretes ao mesmo tempo. O ID do lembrete para cada lembrete selecionado será enviado como parâmetros.
Se houver o risco de entidades externas enviarem pedidos para o URL de destino e for necessário saber quais os pedidos provenientes da integração personalizada da Provet Cloud, os hashes de verificação podem ser utilizados como validação adicional. Quando ativado, um parâmetro adicional chamado "verification" será adicionado aos pedidos e é um resumo de hash MD5 do carimbo de data/hora e do sal de verificação.
Por exemplo, para verificar se o hash de verificação é válido em Python, pode escrever-se uma função como esta:
Quando se utiliza o envio em segundo plano ("Enviar pedido HTTP"), o carimbo de data/hora é gerado quando o pedido é efetivamente enviado. No entanto, quando se utiliza o envio em primeiro plano ("Abrir numa nova janela"), o carimbo de data/hora é gerado quando é carregada uma página que contém o botão de integração personalizado. Isto é feito para gerar o hash de verificação no lado do servidor e evitar expor o sal de verificação aos utilizadores. Os programadores de integrações personalizadas poderão ter de considerar que os utilizadores podem passar algum tempo na página antes de clicarem no botão de integração personalizada.
O Provet Cloud permite uma quantidade limitada de comunicação bidirecional com integrações personalizadas abertas em primeiro plano utilizando a API Window.postMessage(). A janela/guia que abriu a integração personalizada está disponível através do objeto window.opener e, assim, uma mensagem pode ser enviada com window.opener.postMessage(message), em que a mensagem é um comando válido reconhecido pela Provet Cloud.
Atualmente, o único comando válido é "reload", que efectua um recarregamento completo da página na janela/aba que abriu a integração personalizada. Isto pode, por exemplo, ser útil se a integração personalizada atualizar os dados da Provet Cloud através da API REST, e os utilizadores devem ver as últimas alterações quando regressam da integração personalizada.
Atualizado
Comentários
0 comentário
Por favor, entrar para comentar.