Funcionalidade experimental. A integração n8n ainda não está totalmente testada. O administrador ativa-a conscientemente em Definições → Avançado → Outros; enquanto estiver desativada, o separador n8n e este capítulo do manual ficam ocultos, e os endpoints /api/n8n/* permanecem inativos. A integração n8n pertence ao plano Pro. No plano Standard não existe o cartão "Outros" com o respetivo interruptor, pelo que não é possível ativar a integração.

O que é o n8n?

O n8n é uma plataforma de automatização de processos. A integração com o Task Manager funciona nos dois sentidos:

  1. Webhooks de saída (Task Manager → n8n) - a aplicação envia automaticamente notificações para o seu workflow no n8n sempre que algo acontece (tarefa criada, estado alterado, mensagem adicionada, prazo a aproximar-se, etc.).
  2. API de entrada (n8n → Task Manager) - o n8n pode chamar a aplicação para criar tarefas, adicionar mensagens ou obter dados.

Ativar a integração

Clique no ícone da roda dentada (⚙) → separador n8n. O separador divide-se em duas partes: „Automatizações pessoais" - configuração que diz respeito apenas a si, e „Automatizações globais" - definições do sistema partilhadas por todos os utilizadores, visíveis apenas para o administrador. Para que os eventos sejam enviados, o administrador tem de ativar o interruptor „Ativar integração n8n" na parte global.

A. Webhooks de saída - notificações da aplicação para o n8n

Configuração

  1. No separador n8n, clique em «Novo webhook».
  2. Indique o nome do webhook e o URL do webhook copiado do n8n (nó Webhook como trigger, método POST).
  3. Marque os eventos que devem ser enviados.
  4. (Opcional) defina um segredo - a aplicação assinará os pedidos com ele (HMAC), para que o n8n possa verificar a autenticidade.
  5. Guarde. Pode enviar um ping de teste para verificar a ligação.

Eventos disponíveis (seleção)

  • Tarefas: task.created, task.updated, task.status_changed, task.completed, task.deleted, task.deadline_approaching, task.overdue
  • Conversas / mensagens: chat.message_sent, chat.mention, chat.file_uploaded
  • Utilizadores / workspace: user.created, user.login, user.logout, workspace.created
  • Sistema: system.daily_summary, system.weekly_summary

Cada pedido enviado para o n8n contém o nome do evento e os dados (data) com o contexto (por exemplo, id da tarefa, workspace, autor).

B. API de entrada - o n8n controla a aplicação

Configuração

  1. No separador n8n, clique em «Nova chave API».
  2. Copie o token gerado (mostrado apenas uma vez).
  3. No n8n use o node HTTP Request com o cabeçalho de autorização:
    Authorization: Bearer TWÓJ_TOKEN
    As ações são executadas no contexto do utilizador que criou a chave (com as suas permissões e o seu acesso aos espaços de trabalho).

Endpoints disponíveis

  • GET /api/n8n/ping.php - teste do token e healthcheck (devolve informação sobre a chave e o utilizador).
  • GET /api/n8n/workspaces.php - lista dos workspaces disponíveis.
  • GET /api/n8n/users.php - lista de utilizadores (apenas chaves criadas pelo administrador global).
  • GET /api/n8n/tasks.php?workspace_id=&status=&limit= - lista de tarefas.
  • POST /api/n8n/tasks.php - criação de uma tarefa. Corpo JSON:
    {
"workspace_id": 1,
"subject": "Nowe zadanie z n8n",
"description": "Opcjonalny opis",
"priority": "high",
"deadline_date": "2025-12-31",
"status": "none",
"assignees": [2, 5]
}
    A descrição é limpa de HTML perigoso da mesma forma que na aplicação e tem o mesmo limite de tamanho.
  • PATCH /api/n8n/tasks.php - atualização de uma tarefa existente, incluindo a alteração de estado. Corpo JSON (task_id obrigatório, os restantes campos são opcionais - indica apenas o que pretende alterar):
    {
"task_id": 42,
"status": "in_progress",
"priority": "high",
"deadline_date": "2026-08-01",
"subject": "Nowy temat",
"description": "Nowy opis"
}
    • status: none | in_progress | done | cancelled. A alteração do estado funciona exatamente como na aplicação: é adicionada uma entrada ao tópico da tarefa com a indicação «alterou o estado para…», as pessoas atribuídas recebem uma notificação por e-mail e é enviado para o n8n o webhook task.status_changed (e também task.completed quando o estado é done).
    • deadline_date: null limpa o prazo. A alteração do prazo desloca os lembretes associados a ele.
    • Os restantes campos enviam o webhook task.updated.
    • O campo description é guardado da mesma forma que na edição a partir da janela da tarefa: o HTML perigoso é removido, com a encriptação ativada a descrição é gravada na base de dados encriptada, e as marcações da lista to-do mantêm-se nas respetivas posições, mesmo quando a nova descrição altera a ordem dos itens. A tarefa recebe a marca «(editado)» apenas quando o assunto ou o conteúdo da descrição realmente mudaram.
    • Quando a nova descrição elimina uma lista to-do à qual alguém acrescentou itens próprios, nada é guardado (incluindo o estado do mesmo pedido) e recebe um 409 com o código DOPISKI_BEZ_LISTY e o campo indeksy. Para ainda assim eliminar a lista juntamente com os acrescentos, envie novamente a mesma alteração com o campo "usun_dopiski" igual à lista do campo indeksy.
    • Primeiro são guardados o assunto, o prazo, a prioridade e a descrição, só depois o estado - a recusa de gravação da descrição não deixa o estado alterado.
    • Definir novamente o mesmo estado não envia nada (seguro para repetições no n8n).
    • Se o seu node HTTP não suportar o método PATCH - envie o mesmo corpo através de POST: a presença de task_id coloca o endpoint em modo de atualização.
    • Códigos de erro: 400 falta task_id, faltam campos a alterar ou há demasiados itens na lista to-do (TOO_MANY), 413 descrição demasiado grande (PAYLOAD_TOO_LARGE, normalmente uma imagem colada), 422 valor inválido (estado/prioridade/formato de data), 404 a tarefa não existe ou está fora do acesso da chave, 403 sem permissões para alterar o estado/editar, 409 a descrição elimina uma lista com acrescentos de outra pessoa.
  • POST /api/n8n/messages.php - adição de uma mensagem a uma tarefa ou conversa. Corpo JSON:
    {
"entity_type": "task",
"entity_id": 42,
"content": "Treść wiadomości"
}

Exemplos de cenários de automatização

  • Formulário Google → n8n → POST /api/n8n/tasks.php (nova tarefa no Task Manager)
  • E-mail do Gmail com um assunto específico → n8n → tarefa com descrição a partir do conteúdo do e-mail
  • Alteração de estado no Jira → n8n → mensagem/atualização da tarefa associada
  • Webhook de saída task.created → n8n → entrada numa folha de cálculo Google / notificação no Slack
  • task.deadline_approaching → n8n → lembrete por e-mail/SMS sobre o prazo a aproximar-se

Resolução de problemas

  • Sem notificações no n8n - verifique se a integração está ativada, se o webhook está ativo e se o URL está correto. Utilize o «ping de teste» e o diagnóstico no separador n8n: mostra se o endereço do webhook responde (verificado da mesma forma que no envio - sem redirecionamentos e com verificação do certificado, pelo que um n8n com certificado autoassinado aparecerá como inacessível), quantos eventos estão na fila de repetição e quando foi o último envio bem-sucedido.
  • O segredo do webhook é guardado na base de dados encriptado. Após alterar a chave ENCRYPTION_KEY no config.php, os segredos guardados tornam-se ilegíveis - a aplicação passa a enviar os eventos sem assinatura, pelo que deve gerar um novo segredo no webhook e introduzi-lo no n8n.
  • Sem autorização (401) na API de entrada - o token é inválido ou foi eliminado. Crie uma nova chave de API e atualize o cabeçalho Authorization no n8n.
  • A tarefa não é criada - certifique-se de que o workspace_id existe e de que o utilizador da chave tem acesso a ele e permissão para adicionar tarefas.