Configurações para integrações reativas

Objetivo da documentação

Auxiliar no processo de conhecimento e configuração necessários para a integração utilizando Webhooks.

Pré-requisitos

Na rotina "Configurações / Parâmetros", no menu "Service Desk", certifique-se que a opção "Utilizar Webhooks" esteja marcada e a opção "Utilizar Streaming" esteja configurada como "Sim".

Deve possuir as seguinte informações para configurar a integração:

E-mails que serão utilizados caso ocorra alguma falha de integração. É classificado uma falha quando o limite máximo de tentativas de envio for alcançado. Esses e-mails podem ser disponibilizados pelo cliente, para que ele seja informado quando um contrato não foi integrado com sucesso. Essa informação será utilizada no cadastro de Webhooks;
Código de integração para ser informado no cadastro do Serviço.

Configurar o integrador

O usuário que possui o perfil "Administrador" deve acessar a rotina "Manutenções / Integrações / Integradores" e cadastrar os seguintes campos conforme a empresa integradora:

Integrator/Alias: Identificador da integração para o ERP. Conforme a página da Wiki da integradora;
Descrição: Título da integração que irá ser apresentado em outras rotinas;
Tipo de integração: Reativa;
Versão: Conforme a página da Wiki da integradora.

Obs. Campos não informados não devem ser preenchidos.

Configurar os gatilhos

O usuário com o perfil "Administrador" deve acessar a rotina "Manutenções / Integrações / Integrações Webhooks" e cadastrar um gatilho de "Alteração de Contrato" utilizando os dados enviados pela integradora.

Informações

Nome do Webhook: Título para identificação do gatilho;
Integrator: Selecionar a integração cadastrada no passo anterior;
Método HTTP: POST;
Url: URL informada pela integradora;
Limite de tentativas de Integrar: 30;
Lista de E-mails caso chegue ao máximo de tentativas: Informe os e-mails para onde serão enviados os alertas caso a integração não ocorra corretamente. Para cadastrar mais de 1 e-mail, separar por ponto e virgula ";".

Header

Caso sejam necessários campos fixos adicionais, estes podem ser cadastrados como "Headers" no Webhook.

Nome do header: Conforme informado pela integradora;
Valor do header: Conforme informado pela integradora.

Obs. Campos não informados não devem ser preenchidos.

Gatilhos

Alteração de Contrato (Recomendado): Caso esse gatilho seja selecionado no cadastro do Webhook, poderá ser definida qual alteração do contrato gostaria de usar como condição para disparo - Estágio do contrato ou Status do contrato. Recomenda-se utilizar este gatilho e não definir o estágio e o status, onde neste caso, o gatilho será disparado em qualquer alteração de um contrato que possua ligação com um patrimônio ou serviço com o mesmo integrador do Webhook.

Estágio do contrato: caso este tipo seja usado na definição de "gatilho", poderá ser definida, entre uma lista de opções, qual estágio do contrato irá disparar o "gatilho". Como exemplo de estágios de um contrato temos "Em aprovação" e "Cancelado".
Status do contrato: Caso este tipo seja usado na definição de "gatilho", poderá ser definida, entre uma lista de opções, qual status do contrato irá disparar o "gatilho". Como exemplo de status de um contrato temos "Normal" e "Cortesia".
Status do contrato e Estágio do contrato juntos: Poderão ser utilizados os dois gatilhos juntos, pois ambos se referem a contrato. Neste caso, temos um exemplo de webhook cujo integrador é "empresa1" e seu gatilho selecionado é Alteração de Contrato-> Status do contrato-> Cortesia E Estágio do contrato -> Normal. Neste caso, o gatilho será disparado se um contrato que possua serviço ou patrimônio do mesmo tipo do integrador do Webhook tenha o status mudado para cortesia e seu estágio seja aprovado; ou seu status seja cortesia e seja mudado para integrado.

Alteração de Serviço (Contrato): Caso este "gatilho" seja selecionado, o mesmo será disparado quando um serviço que possua o mesmo integrador definido no Webhook seja adicionado, excluído ou alterado em um contrato através da troca de um serviço.

Alteração de Patrimônio (Contrato): Caso este "gatilho" seja selecionado, o mesmo será disparado quando um patrimônio que possua o mesmo integrador definido no Webhook seja vinculado em um contrato. Esse vínculo pode ocorrer através de uma solicitação vinculada ao contrato, em que um patrimônio seja vinculado e tenha sua nota emitida.

Cadastrar um serviço

Deve cadastrar um serviço para cada código de integração informado pela integradora na rotina "Faturamento / Cadastros / Produtos/Serviços". É um procedimento parecido com integrações do tipo passiva também oferecidas pelo ERPVoalle, cuja documentação pode ser encontrada no link

Testar a integração

Deve criar um contrato teste onde neste deverá ser inserindo o serviço cadastrado no passo anterior.

Para realização dos testes, devem ser feitas alterações na situação, estágios, exclusão e re-inserção do serviço no contrato. Pode ser solicitada a orientação da equipe de integrações sobre os testes a serem realizados.

Cada teste deve ser acompanhado por uma resposta de sucesso. As requisições podem ser visualizadas pelo usuário administrador na rotina "Manutenções / Integrações / Webhook Data Storage", para saber mais sobre esta rotina acesse este link. Caso a requisição enviada não obtenha um StatusCode 200 na resposta, o ERP entende que a tentativa de envio dos dados fracassou e fará novas tentativas até o limite de tentativas esgotar. Caso sejam feitas algumas tentativas sem sucesso durante os testes, a integradora deve ser informada.

Após os testes realizados com sucesso, a integração está pronta para ser inserida em outros contratos.