O que é a integração n8n no Task Manager?
A integração n8n do Task Manager transfere dados entre tarefas e outros sistemas. Um pedido enviado através de um formulário pode tornar-se uma tarefa sem ser necessário voltar a introduzir os dados. A criação de uma tarefa pode gerar uma entrada numa folha de cálculo do Google ou uma notificação no Slack. A equipa continua a trabalhar no Task Manager como habitualmente.
A integração n8n pertence à versão Pro. Trata-se de uma função experimental e desativada por predefinição. O administrador ativa-a em Definições → Avançado → Outros. Quando está desativada, o separador n8n não aparece na interface e os endpoints /api/n8n/* rejeitam os pedidos com o código 503. O capítulo do manual sobre o n8n também desaparece do contexto do Assistente de IA.
O n8n é uma plataforma independente para criar fluxos entre aplicações. O Task Manager envia-lhe eventos e também recebe chamadas.
Como funciona?
Os dados saem do Task Manager para o n8n através de um webhook. Indica o nome, o URL do nó *Webhook* no n8n e seleciona os eventos. Também pode adicionar um segredo para assinar os pedidos (HMAC). Pode escolher entre 26 eventos, incluindo task.created, task.status_changed, task.completed e chat.message_sent; os eventos de sistema (system.daily_summary e os restantes system.*), bem como user.created, são enviados exclusivamente para webhooks globais criados por um administrador. Cada pedido inclui o nome do evento, a marca temporal e dados contextuais. Antes de criar todo o fluxo, pode enviar um ping de teste.
No sentido inverso, é utilizada uma chave API. O token no formato tm_live_<32hex> é apresentado apenas uma vez. No n8n, indique-o no cabeçalho Authorization: Bearer. Os endpoints disponíveis são ping.php, workspaces.php, users.php, tasks.php e messages.php. POST /api/n8n/tasks.php cria uma tarefa com assunto, descrição, prioridade, prazo e lista de pessoas atribuídas. PATCH atualiza uma tarefa existente. É necessário indicar task_id; os restantes campos são opcionais. Se o nó HTTP não suportar PATCH, pode enviar o body através de POST. A presença de task_id coloca o endpoint em modo de atualização.
A alteração de estado através do n8n segue o mesmo processo que uma alteração na aplicação. No tópico da tarefa surge uma entrada «alterou o estado para…», as pessoas atribuídas recebem um e-mail e o Task Manager envia task.status_changed (e também task.completed quando o estado passa a done). Definir novamente o mesmo estado não envia outro evento. Os webhooks que falham são colocados numa fila. A fila prevê intervalos de 60, 300 e 1800 segundos e um máximo de quatro tentativas, mas as novas tentativas são executadas pelo cron retry ou pelo processamento da fila durante alguns pedidos à aplicação. Sem cron e sem atividade na aplicação, não haverá novas tentativas nesses intervalos. Uma falha na integração não impede o trabalho no programa.
A chave utiliza as permissões do utilizador que a criou e o respetivo acesso aos espaços de trabalho. O ficheiro users.php só está disponível para chaves de administrador global. Os endereços de webhook em intervalos de IP privados e reservados são bloqueados; a política n8n_private_network_policy aceita os valores off, admin e all. Se o valor for inválido, comporta-se como off.
O que ganha?
Não precisa de copiar o pedido do cliente do formulário para uma tarefa. De manhã, pode começar a trabalhar no pedido em vez de transferir dados entre janelas.
Também não precisa de se lembrar de atualizar dois sistemas quando o trabalho estiver concluído. Quando a tarefa é fechada, a informação pode seguir para o sistema seguinte através do fluxo preparado. O cliente não tem de esperar que alguém registe manualmente a alteração do outro lado.
A sua equipa não precisa de aprender a usar o n8n para tirar partido da integração pronta a utilizar. Quando uma tarefa é fechada por um fluxo externo, as pessoas atribuídas recebem um e-mail e fica registada uma entrada sobre a alteração no tópico. Uma falha na integração não interrompe o trabalho nas tarefas.
Exemplo do trabalho diário
Uma empresa de assistência técnica recebe pedidos num sistema externo de tickets. Um fluxo no n8n recebe um novo ticket e envia POST /api/n8n/tasks.php. É criada uma tarefa com o endereço na descrição, prioridade high e prazo em deadline_date - no workspace a que o proprietário da chave tem acesso e com as pessoas da lista assignees que também tenham acesso a esse workspace.
Quando o técnico conclui a tarefa, o Task Manager envia task.completed para o webhook que tenha este evento selecionado, e o fluxo atualiza o estado no sistema do cliente. Um webhook separado para task.deadline_approaching (o evento é emitido por uma tarefa recorrente «deadline», pelo que requer que o cron esteja ativo) pode iniciar o envio de um SMS a lembrar que o prazo se aproxima. O técnico não precisa de usar o n8n.
Perguntas mais frequentes
A integração n8n está disponível na versão Standard?
Não, essa função pertence à versão Pro. Na versão Standard não existe o interruptor da integração nas Definições, por isso não é possível ativá-la.
A integração n8n funciona logo após a instalação?
Não. Esta funcionalidade é experimental e está desativada por predefinição. O administrador ativa-a em Definições → Avançadas → Outros. Até lá, o separador n8n fica oculto e os endpoints /api/n8n/* devolvem o código 503.
As integrações exigem um programador?
Para criar um fluxo no n8n, é útil contar com alguém com conhecimentos técnicos. É necessário copiar o endereço do webhook, indicar um token e preparar o body JSON. Não é preciso ter esses conhecimentos para utilizar um fluxo já criado.
Posso alterar o estado de uma tarefa externamente?
Sim. Envie um pedido PATCH para /api/n8n/tasks.php com task_id e o estado none, in_progress, done ou cancelled. A alteração cria uma entrada no tópico da tarefa, envia um e-mail às pessoas atribuídas e aciona um webhook de saída.
O que acontece quando o n8n não responde?
Os webhooks que falham são colocados numa fila. A fila prevê intervalos de 60, 300 e 1800 segundos e um máximo de quatro tentativas, mas as novas tentativas são executadas pelo cron retry ou pelo processamento da fila durante alguns pedidos à aplicação. Sem cron e sem atividade na aplicação, não haverá novas tentativas nesses intervalos. Uma falha na integração não impede o trabalho no programa.
Desativar a integração elimina a configuração?
Não. Os webhooks e as chaves API permanecem na base de dados e ficam novamente disponíveis quando a integração for reativada.