Gestor de Instalação e Execução do Widget de Tarefas do Bitrix24 - Fluxo de trabalho n8n

Desenvolvedores de aplicações Bitrix24 que necessitam de um backend fiável para gestão de instalações e tokens.
Utilizadores à procura de modelos n8n robustos para interações complexas com webhooks.
Especialistas em automação que implementam widgets personalizados em ambientes de CRM.
Engenheiros à procura de uma solução auto-hospedada (self-hosted) para o manuseamento da API do Bitrix24.

O desenvolvimento de aplicações personalizadas para plataformas como o Bitrix24 exige um manuseamento complexo dos tokens OAuth, dos 'callbacks' de instalação e da entrega de conteúdo dinâmico. Este poderoso fluxo de trabalho n8n resolve estes desafios ao funcionar como o gestor central de todos os eventos do Bitrix24 relacionados com a sua aplicação de widget personalizada. O principal valor deste modelo n8n é a sua capacidade de gerir sem problemas o acordo de ligação inicial da instalação — guardando os tokens de acesso críticos em disco — e, em seguida, utilizando essas credenciais armazenadas durante a execução para obter e exibir informações contextuais (como detalhes da tarefa) num separador de visualização de tarefas do Bitrix
24.

Cada vez que o Bitrix24 envia um pedido (seja para instalação ou visualização do widget), esta configuração específica do nó n8n garante a autenticação segura e respostas imediatas e personalizadas, demonstrando a eficiência de um fluxo de trabalho n8n bem concebido.

Todo o processo começa com o 'trigger' (gatilho) n8n designado, o nó Webhook, que fica a escutar pedidos POST vindos do Bitrix
24.

1. Gatilho e Inicialização: O gatilho n8n Bitrix24 Handler recebe o evento. O nó n8n Extract Credentials analisa imediatamente o 'payload' JSON recebido para recuperar o domínio, os tokens de acesso e os tokens de atualização.


2. Determinação do Evento: O nó de Código Check Event Type analisa o pedido para distinguir entre um evento de instalação da aplicação (ONAPPINSTALL) e um pedido de posicionamento em tempo de execução (por exemplo, visualização de uma tarefa).


3. Caminho de Instalação: Se for uma instalação, o fluxo de trabalho ramifica. Se a instalação ainda não estiver concluída, o sistema utiliza o nó n8n Set Settings Data para formatar os tokens, converte-os num ficheiro JSON (Create Settings File) e guarda a configuração utilizando o nó n8n Save Installation Settings (Ler/Escrever Ficheiro). Em seguida, regista o posicionamento do widget (nó de Pedido HTTP Register Placement) e conclui o processo com a resposta do webhook Installation Response.


4. Caminho de Execução (Visualização do Widget): Se o evento for um pedido de execução, o sistema recupera os dados de autenticação guardados anteriormente utilizando os nós n8n Read Installation Settings e Extract Installation Settings. O nó Merge request data with installation settings prepara o contexto de dados necessário.


5. Processamento e Recuperação de Dados: O nó de Função Process Settings extrai informações específicas do contexto, como o taskId. O nó 'If' Has Valid Settings? valida as credenciais. Se forem válidas, o nó de Pedido HTTP n8n Get Task Data utiliza o token de acesso Bitrix24 guardado para consultar a API do Bitrix24 em busca de informações detalhadas da tarefa.


6. Geração de Resposta: O nó de Função Format Task Data converte os dados brutos da tarefa em HTML estruturado. Por fim, o nó n8n Task View Response envia este HTML de volta ao Bitrix24, que o renderiza dentro do widget de tarefas personalizado. Se as definições não fossem válidas, é devolvida uma Error Response. Esta lógica complexa demonstra uma aplicação poderosa de um fluxo de trabalho n8n.

Para implementar este fluxo de trabalho n8n abrangente, siga estes passos:

1. Importar o Fluxo de Trabalho n8n: Copie os dados JSON fornecidos. Na sua instância n8n, navegue até 'Workflows' e clique em 'New' (Novo). Selecione 'Import from JSON' e cole o código.


2. Configurar o Gatilho Webhook: Localize o nó de gatilho n8n Bitrix24 Handler. O Caminho (Path) está definido como bitrix24/widgethandler.php. Ative o fluxo de trabalho para gerar o URL do webhook completo. Este URL tem de ser registado nas definições da sua aplicação Bitrix24 como o URL do gestor (handler) para os eventos de instalação e posicionamento.


3. Definir Credenciais de Espaço Reservado (Placeholder): O nó n8n Extract Credentials contém valores de espaço reservado codificados (ex: local.67b8a796e92127.82791242). Estes são geralmente substituídos pelos dados reais do Bitrix24 durante o webhook de instalação, mas poderá ter de os ajustar se a sua aplicação utilizar IDs/Segredos de Cliente estáticos diferentes. Certifique-se de que a sua aplicação Bitrix24 está configurada corretamente para enviar estes tokens iniciais.


4. Acesso ao Sistema de Ficheiros: O fluxo de trabalho utiliza o nó n8n ReadWriteFile para guardar e ler os tokens de autenticação do Bitrix24. Certifique-se de que o seu ambiente de alojamento n8n tem as permissões necessárias para aceder ao caminho /data/files/hotline_files/ (ou ajuste a variável settingsFilePath no nó Extract Credentials para um local acessível pela sua instância n8n).


5. Ativar: Guarde e ative o fluxo de trabalho n8n. A automação ficará agora a escutar os eventos do Bitrix24.

Bitrix24 Handler (Gatilho Webhook n8n): O ponto de entrada do fluxo de trabalho n8n. Está configurado para escutar pedidos POST num caminho específico, iniciando a sequência de operações tanto para os pedidos de instalação como para os de visualização de tarefas.
Extract Credentials (Nó Set n8n): Essencial para a segurança, este nó extrai parâmetros de autenticação dinâmicos (como accesstoken e refreshtoken) enviados pelo Bitrix24, preparando-os para uso em pedidos HTTP subsequentes e para serem guardados no armazenamento.
Check Event Type (Nó Code n8n): Um nó de script personalizado que analisa o corpo do pedido recebido para diferenciar entre 'callbacks' de instalação da aplicação e eventos de posicionamento do widget, fornecendo lógica crucial de controlo de fluxo para o fluxo de trabalho n8n.
Is Installation? (Nó If n8n): Um nó n8n de lógica central que direciona o fluxo com base em saber se o pedido atual faz parte do processo de instalação da aplicação (isInstallation: true).
Set Settings Data & Save Installation Settings (Nós Set & ReadWriteFile n8n): Estes nós trabalham em conjunto no modelo n8n para serializar os tokens Bitrix24 recebidos (incluindo expiração e domínio) e escrevê-los de forma segura num ficheiro JSON no sistema de ficheiros local, garantindo persistência para uso posterior em tempo de execução.
Register Placement (Nó HTTP Request n8n): Executa uma chamada à API do Bitrix24 para ligar o URL do gestor de widget personalizado ao posicionamento desejado, especificamente TASKVIEWTAB, garantindo que o URL do webhook n8n está corretamente integrado na interface do Bitrix24.
Read Installation Settings & Process Settings (Nós ReadWriteFile & Function n8n): No acesso em tempo de execução, estes nós recuperam e processam os tokens armazenados, garantindo que o fluxo de trabalho n8n tem as credenciais e o contexto necessários (como o taskId específico) para prosseguir com as consultas à API.
Get Task Data (Nó HTTP Request n8n): Utiliza os tokens de acesso validados para efetuar uma chamada autenticada à API do Bitrix24 (tasks.task.get), obtendo os detalhes necessários para a exibição do widget. Este é um passo crítico na fase de execução deste fluxo de trabalho n8n.

• Task View Response (Nó RespondToWebhook n8n): A ação final para pedidos de execução. Empacota o HTML gerado pelo nó de Função anterior e envia-o imediatamente de volta ao Bitrix24, exibindo o conteúdo do widget personalizado. Se as definições não fossem válidas, é devolvida uma Error Response. Esta lógica complexa demonstra uma aplicação poderosa de um fluxo de trabalho n8n.