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/* ficam inativos.

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 de 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 comuns a 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 assina com ele os pedidos (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 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]
}
  • 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 - indique apenas o que quer 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 de estado funciona exatamente como na aplicação: no tópico da tarefa aparece uma entrada „alterou o estado para…", as pessoas atribuídas recebem uma notificação por e-mail e é enviado ao n8n o webhook task.status_changed (e task.completed quando é 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.
    • 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 por POST: a presença de task_id muda o endpoint para o modo de atualização.
    • Códigos de erro: 400 falta task_id ou não há campos para alterar, 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.
  • POST /api/n8n/messages.php - adição de 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».
  • Sem autorização (401) na API de entrada - o token é inválido ou foi eliminado. Crie uma nova chave 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.