IDs de Workflow

Os IDs de workflow são identificadores únicos que permitem referenciar, rastrear e gerenciar workflows de forma programática. Esta seção aborda como entender, usar e gerenciar IDs de workflow no n8n.

Visão Geral

Os IDs de workflow são fundamentais para:

• Identificação única de workflows no sistema
• Referência programática via API
• Rastreamento de execuções e mudanças
• Integração com sistemas externos
• Auditoria e compliance

Estrutura dos IDs

Formato Padrão

Os IDs de workflow seguem um formato específico:

javascript\n// Estrutura do ID de workflow\nconst estruturaId = {\n  // Formato: UUID v4\n  formato: 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx',\n  \n  // Exemplo real\n  exemplo: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',\n  \n  // Componentes\n  componentes: {\n    versao: '4', // Versão do UUID\n    variante: '8', // Variante do UUID\n    timestamp: 'timestamp-embedded', // Timestamp embutido\n    aleatorio: 'random-bytes' // Bytes aleatórios\n  }\n};\n

\n\n### Tipos de IDs\n\n

javascript\n// Diferentes tipos de identificadores\nconst tiposIds = {\n  // ID interno do n8n\n  interno: {\n    formato: 'uuid-v4',\n    exemplo: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',\n    uso: 'Identificação interna no banco de dados'\n  },\n  \n  // ID de execução\n  execucao: {\n    formato: 'uuid-v4',\n    exemplo: 'b2c3d4e5-f6g7-8901-bcde-f23456789012',\n    uso: 'Identificação única de cada execução'\n  },\n  \n  // ID de versão\n  versao: {\n    formato: 'semantic-versioning',\n    exemplo: '1.2.3',\n    uso: 'Controle de versão do workflow'\n  },\n  \n  // ID customizado\n  customizado: {\n    formato: 'user-defined',\n    exemplo: 'vendas-automacao-2024',\n    uso: 'Identificação amigável para usuários'\n  }\n};\n

\n\n## Geração de IDs\n\n### Geração Automática\n\nOs IDs são gerados automaticamente pelo n8n:\n\n

javascript\n// Geração automática de ID\nconst gerarIdAutomatico = () => {\n  // O n8n gera automaticamente UUIDs v4\n  const uuid = require('uuid');\n  return uuid.v4();\n};\n\n// Exemplo de uso\nconst novoId = gerarIdAutomatico();\nconsole.log(novoId); // a1b2c3d4-e5f6-7890-abcd-ef1234567890\n

\n\n### Geração Customizada\n\nPara casos especiais, você pode gerar IDs customizados:\n\n

javascript\n// Gerar ID customizado\nconst gerarIdCustomizado = (prefixo, sufixo) => {\n  const timestamp = Date.now();\n  const aleatorio = Math.random().toString(36).substring(2, 8);\n  \n  return `${prefixo}-${timestamp}-${aleatorio}${sufixo ? `-${sufixo}` : ''}`;\n};\n\n// Exemplos de uso\nconst idVendas = gerarIdCustomizado('vendas', 'automacao');\nconsole.log(idVendas); // vendas-1703123456789-abc123-automacao\n\nconst idFinanceiro = gerarIdCustomizado('financeiro', 'conciliacao');\nconsole.log(idFinanceiro); // financeiro-1703123456789-def456-conciliacao\n

\n\n## Obtenção de IDs\n\n### Via Interface Web\n\nPara obter o ID de um workflow via interface:\n\n1. Abra o workflow no editor\n2. Clique no menu (⋮) no canto superior direito\n3. Selecione "Copy ID" no menu\n4. O ID será copiado para a área de transferência\n\n### Via API\n\n

javascript\n// Obter ID de workflow via API\nconst obterIdWorkflow = async (nomeWorkflow) => {\n  const response = await fetch('/api/v1/workflows', {\n    method: 'GET',\n    headers: {\n      'Authorization': 'Bearer YOUR_API_KEY'\n    },\n    params: {\n      name: nomeWorkflow\n    }\n  });\n  \n  const workflows = await response.json();\n  \n  if (workflows.length > 0) {\n    return workflows[0].id;\n  }\n  \n  throw new Error(`Workflow "${nomeWorkflow}" não encontrado`);\n};\n\n// Exemplo de uso\nconst id = await obterIdWorkflow('Automação de Vendas');\nconsole.log(id); // a1b2c3d4-e5f6-7890-abcd-ef1234567890\n

\n\n### Listar IDs de Múltiplos Workflows\n\n

javascript\n// Listar IDs de workflows com filtros\nconst listarIdsWorkflows = async (filtros = {}) => {\n  const response = await fetch('/api/v1/workflows', {\n    method: 'GET',\n    headers: {\n      'Authorization': 'Bearer YOUR_API_KEY'\n    },\n    params: filtros\n  });\n  \n  const workflows = await response.json();\n  \n  return workflows.map(workflow => ({\n    id: workflow.id,\n    name: workflow.name,\n    active: workflow.active,\n    updatedAt: workflow.updatedAt\n  }));\n};\n\n// Exemplo: Listar IDs de workflows ativos\nconst workflowsAtivos = await listarIdsWorkflows({\n  active: true\n});\n\n// Exemplo: Listar IDs de workflows por tag\nconst workflowsVendas = await listarIdsWorkflows({\n  tags: ['vendas']\n});\n

\n\n## Uso de IDs\n\n### Referência via API\n\n

javascript\n// Usar ID para operações na API\nconst operacoesComId = {\n  // Obter workflow por ID\n  obterWorkflow: async (id) => {\n    const response = await fetch(`/api/v1/workflows/${id}`, {\n      method: 'GET',\n      headers: {\n        'Authorization': 'Bearer YOUR_API_KEY'\n      }\n    });\n    \n    return response.json();\n  },\n  \n  // Executar workflow por ID\n  executarWorkflow: async (id, dados = {}) => {\n    const response = await fetch(`/api/v1/workflows/${id}/execute`, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        'Authorization': 'Bearer YOUR_API_KEY'\n      },\n      body: JSON.stringify(dados)\n    });\n    \n    return response.json();\n  },\n  \n  // Atualizar workflow por ID\n  atualizarWorkflow: async (id, dados) => {\n    const response = await fetch(`/api/v1/workflows/${id}`, {\n      method: 'PUT',\n      headers: {\n        'Content-Type': 'application/json',\n        'Authorization': 'Bearer YOUR_API_KEY'\n      },\n      body: JSON.stringify(dados)\n    });\n    \n    return response.json();\n  },\n  \n  // Excluir workflow por ID\n  excluirWorkflow: async (id) => {\n    const response = await fetch(`/api/v1/workflows/${id}`, {\n      method: 'DELETE',\n      headers: {\n        'Authorization': 'Bearer YOUR_API_KEY'\n      }\n    });\n    \n    return response.json();\n  }\n};\n\n// Exemplo de uso\nconst workflow = await operacoesComId.obterWorkflow('a1b2c3d4-e5f6-7890-abcd-ef1234567890');\nconst execucao = await operacoesComId.executarWorkflow('a1b2c3d4-e5f6-7890-abcd-ef1234567890', {\n  data: { lead: 'novo-lead@email.com' }\n});\n

\n\n### Integração com Sistemas Externos\n\n

javascript\n// Integrar IDs com sistemas externos\nconst integracaoIds = {\n  // Mapear ID do n8n com ID externo\n  mapearId: async (idN8n, idExterno, sistema) => {\n    const mapeamento = {\n      idN8n: idN8n,\n      idExterno: idExterno,\n      sistema: sistema,\n      criadoEm: new Date().toISOString()\n    };\n    \n    // Salvar mapeamento no banco de dados\n    await salvarMapeamento(mapeamento);\n    \n    return mapeamento;\n  },\n  \n  // Obter ID externo por ID do n8n\n  obterIdExterno: async (idN8n, sistema) => {\n    const mapeamento = await buscarMapeamento(idN8n, sistema);\n    return mapeamento ? mapeamento.idExterno : null;\n  },\n  \n  // Obter ID do n8n por ID externo\n  obterIdN8n: async (idExterno, sistema) => {\n    const mapeamento = await buscarMapeamentoPorExterno(idExterno, sistema);\n    return mapeamento ? mapeamento.idN8n : null;\n  }\n};\n\n// Exemplo: Integração com CRM\nconst idN8n = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';\nconst idCrm = 'CRM-2024-001';\n\nawait integracaoIds.mapearId(idN8n, idCrm, 'salesforce');\nconst idExterno = await integracaoIds.obterIdExterno(idN8n, 'salesforce');\n

\n\n## Rastreamento e Auditoria\n\n### Histórico de Mudanças\n\n

javascript\n// Rastrear mudanças por ID\nconst rastreamentoIds = {\n  // Registrar mudança\n  registrarMudanca: async (idWorkflow, tipo, detalhes) => {\n    const mudanca = {\n      workflowId: idWorkflow,\n      tipo: tipo, // 'criado', 'atualizado', 'executado', 'excluido'\n      detalhes: detalhes,\n      timestamp: new Date().toISOString(),\n      usuario: 'usuario@empresa.com'\n    };\n    \n    await salvarMudanca(mudanca);\n    return mudanca;\n  },\n  \n  // Obter histórico de mudanças\n  obterHistorico: async (idWorkflow, limite = 100) => {\n    const mudancas = await buscarMudancas(idWorkflow, limite);\n    return mudancas.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));\n  },\n  \n  // Obter última mudança\n  obterUltimaMudanca: async (idWorkflow) => {\n    const mudancas = await rastreamentoIds.obterHistorico(idWorkflow, 1);\n    return mudancas[0] || null;\n  }\n};\n\n// Exemplo de uso\nawait rastreamentoIds.registrarMudanca(\n  'a1b2c3d4-e5f6-7890-abcd-ef1234567890',\n  'executado',\n  { resultado: 'sucesso', duracao: '2.5s' }\n);\n\nconst historico = await rastreamentoIds.obterHistorico('a1b2c3d4-e5f6-7890-abcd-ef1234567890');\n

\n\n### Logs de Auditoria\n\n

javascript\n// Logs de auditoria por ID\nconst auditoriaIds = {\n  // Log de acesso\n  logAcesso: async (idWorkflow, acao, usuario) => {\n    const log = {\n      workflowId: idWorkflow,\n      acao: acao, // 'visualizar', 'editar', 'executar', 'excluir'\n      usuario: usuario,\n      timestamp: new Date().toISOString(),\n      ip: 'SEU_IP_INTERNO00',\n      userAgent: 'Mozilla/5.0...'\n    };\n    \n    await salvarLogAuditoria(log);\n    return log;\n  },\n  \n  // Obter logs de auditoria\n  obterLogsAuditoria: async (idWorkflow, periodo) => {\n    const logs = await buscarLogsAuditoria(idWorkflow, periodo);\n    return logs.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));\n  },\n  \n  // Relatório de auditoria\n  relatorioAuditoria: async (idWorkflow) => {\n    const logs = await auditoriaIds.obterLogsAuditoria(idWorkflow, '30d');\n    \n    return {\n      totalAcessos: logs.length,\n      acessosPorUsuario: agruparPorUsuario(logs),\n      acessosPorAcao: agruparPorAcao(logs),\n      ultimoAcesso: logs[0] || null\n    };\n  }\n};\n\n// Exemplo de uso\nawait auditoriaIds.logAcesso(\n  'a1b2c3d4-e5f6-7890-abcd-ef1234567890',\n  'executar',\n  'joao@empresa.com'\n);\n\nconst relatorio = await auditoriaIds.relatorioAuditoria('a1b2c3d4-e5f6-7890-abcd-ef1234567890');\n

\n\n## IDs em URLs e Webhooks\n\n### URLs com IDs\n\n

javascript\n// URLs que usam IDs de workflow\nconst urlsComIds = {\n  // URL do editor\n  editor: (id) => `https://n8n.empresa.com/workflow/${id}`,\n  \n  // URL da API\n  api: (id) => `https://n8n.empresa.com/api/v1/workflows/${id}`,\n  \n  // URL de execução\n  execucao: (id) => `https://n8n.empresa.com/api/v1/workflows/${id}/execute`,\n  \n  // URL de webhook\n  webhook: (id) => `https://n8n.empresa.com/webhook/${id}`,\n  \n  // URL de histórico\n  historico: (id) => `https://n8n.empresa.com/workflow/${id}/history`\n};\n\n// Exemplo de uso\nconst id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';\nconsole.log(urlsComIds.editor(id)); // https://n8n.empresa.com/workflow/a1b2c3d4-e5f6-7890-abcd-ef1234567890\nconsole.log(urlsComIds.webhook(id)); // https://n8n.empresa.com/webhook/a1b2c3d4-e5f6-7890-abcd-ef1234567890\n

\n\n### Webhooks com IDs\n\n

javascript\n// Configurar webhook com ID\nconst configurarWebhook = async (idWorkflow, configuracao) => {\n  const webhook = {\n    workflowId: idWorkflow,\n    path: configuracao.path || `webhook-${idWorkflow}`,\n    method: configuracao.method || 'POST',\n    authentication: configuracao.authentication || 'none',\n    active: configuracao.active || true\n  };\n  \n  const response = await fetch(`/api/v1/workflows/${idWorkflow}/webhooks`, {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      'Authorization': 'Bearer YOUR_API_KEY'\n    },\n    body: JSON.stringify(webhook)\n  });\n  \n  return response.json();\n};\n\n// Exemplo: Configurar webhook para automação de vendas\nconst configuracaoWebhook = {\n  path: 'vendas-lead',\n  method: 'POST',\n  authentication: 'header',\n  active: true\n};\n\nconst webhook = await configurarWebhook('a1b2c3d4-e5f6-7890-abcd-ef1234567890', configuracaoWebhook);\n

\n\n## IDs em Templates e Compartilhamento\n\n### Templates com IDs\n\n

javascript\n// Criar template com ID\nconst criarTemplateComId = async (idWorkflow, metadata) => {\n  const workflow = await obterWorkflow(idWorkflow);\n  \n  const template = {\n    ...workflow,\n    templateId: `template-${idWorkflow}`,\n    metadata: {\n      ...metadata,\n      originalId: idWorkflow,\n      createdAt: new Date().toISOString(),\n      version: '1.0.0'\n    }\n  };\n  \n  return template;\n};\n\n// Exemplo: Criar template de automação de vendas\nconst metadata = {\n  name: 'Automação de Vendas - Template',\n  description: 'Template para automação de processo de vendas',\n  category: 'Vendas',\n  tags: ['vendas', 'crm', 'automação']\n};\n\nconst template = await criarTemplateComId('a1b2c3d4-e5f6-7890-abcd-ef1234567890', metadata);\n

\n\n### Compartilhamento com IDs\n\n

javascript\n// Compartilhar workflow por ID\nconst compartilharPorId = async (idWorkflow, usuarios, permissoes) => {\n  const compartilhamento = {\n    workflowId: idWorkflow,\n    usuarios: usuarios,\n    permissoes: permissoes,\n    compartilhadoEm: new Date().toISOString(),\n    compartilhadoPor: 'admin@empresa.com'\n  };\n  \n  const response = await fetch(`/api/v1/workflows/${idWorkflow}/share`, {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      'Authorization': 'Bearer YOUR_API_KEY'\n    },\n    body: JSON.stringify(compartilhamento)\n  });\n  \n  return response.json();\n};\n\n// Exemplo: Compartilhar workflow de vendas\nconst usuarios = ['joao@empresa.com', 'maria@empresa.com'];\nconst permissoes = ['read', 'execute'];\n\nawait compartilharPorId('a1b2c3d4-e5f6-7890-abcd-ef1234567890', usuarios, permissoes);\n

\n\n## Validação e Segurança\n\n### Validação de IDs\n\n

javascript\n// Validar formato de ID\nconst validarId = (id) => {\n  // Regex para UUID v4\n  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;\n  \n  return {\n    valido: uuidRegex.test(id),\n    formato: 'uuid-v4',\n    comprimento: id.length,\n    caracteres: id.replace(/[^0-9a-f-]/gi, '').length === id.length\n  };\n};\n\n// Exemplo de uso\nconst id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';\nconst validacao = validarId(id);\nconsole.log(validacao); // { valido: true, formato: 'uuid-v4', comprimento: 36, caracteres: 36 }\n

\n\n### Segurança de IDs\n\n

javascript\n// Medidas de segurança para IDs\nconst segurancaIds = {\n  // Verificar permissões de acesso\n  verificarPermissoes: async (idWorkflow, usuario) => {\n    const workflow = await obterWorkflow(idWorkflow);\n    const permissoes = await obterPermissoesUsuario(usuario);\n    \n    return {\n      podeVisualizar: permissoes.includes('read') || workflow.owner === usuario,\n      podeEditar: permissoes.includes('write') || workflow.owner === usuario,\n      podeExecutar: permissoes.includes('execute') || workflow.owner === usuario,\n      podeExcluir: permissoes.includes('admin') || workflow.owner === usuario\n    };\n  },\n  \n  // Log de tentativas de acesso\n  logTentativaAcesso: async (idWorkflow, usuario, sucesso) => {\n    const log = {\n      workflowId: idWorkflow,\n      usuario: usuario,\n      sucesso: sucesso,\n      timestamp: new Date().toISOString(),\n      ip: 'SEU_IP_INTERNO00'\n    };\n    \n    await salvarLogSeguranca(log);\n    return log;\n  },\n  \n  // Rate limiting por ID\n  verificarRateLimit: async (idWorkflow, usuario) => {\n    const tentativas = await contarTentativas(idWorkflow, usuario, '1h');\n    const limite = 100; // 100 tentativas por hora\n    \n    return {\n      permitido: tentativas < limite,\n      tentativasRestantes: limite - tentativas,\n      resetEm: new Date(Date.now() + 3600000) // 1 hora\n    };\n  }\n};\n\n// Exemplo de uso\nconst permissoes = await segurancaIds.verificarPermissoes('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'joao@empresa.com');\nconst rateLimit = await segurancaIds.verificarRateLimit('a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'joao@empresa.com');\n

\n\n## Workflows de Gerenciamento de IDs\n\n### Workflow: Backup de IDs\n\n

mermaid\ngraph TD\n    A[Schedule: Diário às 2h] --> B[Code: Listar Todos os IDs]\n    B --> C[Code: Validar IDs]\n    C --> D[Code: Criar Backup]\n    D --> E[HTTP Request: Salvar no S3]\n    E --> F[Code: Verificar Integridade]\n    F --> G[Send Email: Backup Concluído]\n

\n\n### Workflow: Auditoria de IDs\n\n

mermaid\ngraph TD\n    A[Schedule: Semanal] --> B[Code: Analisar Logs de Acesso]\n    B --> C[Code: Identificar Anomalias]\n    C --> D[Decision: Anomalia Encontrada?]\n    D -->|Sim| E[Code: Gerar Alerta]\n    D -->|Não| F[Code: Gerar Relatório]\n    E --> G[Send Email: Alerta de Segurança]\n    F --> H[Send Email: Relatório Semanal]\n

Boas Práticas

Nomenclatura e Organização

• Use IDs consistentes em toda a organização
• Documente mapeamentos de IDs externos
• Implemente validação de IDs
• Mantenha histórico de mudanças

Segurança

• Valide permissões antes de usar IDs
• Implemente rate limiting para APIs
• Log todas as operações com IDs
• Use HTTPS para todas as operações

Performance

• Cache IDs frequentemente usados
• Use índices no banco de dados
• Implemente paginação para listas grandes
• Otimize consultas por ID

Troubleshooting

Problemas Comuns

ID não encontrado:

• Verificar se o ID está correto
• Verificar se o workflow existe
• Verificar permissões de acesso
• Verificar se o ID não foi excluído

ID inválido:

• Verificar formato do UUID
• Verificar caracteres especiais
• Verificar comprimento correto
• Verificar encoding

Problemas de performance:

• Verificar índices no banco de dados
• Verificar cache de IDs
• Verificar consultas otimizadas
• Verificar rate limiting

Recursos Adicionais

Documentação Oficial

• Workflow IDs
• API Reference

Ferramentas Relacionadas

• n8n CLI: Gerenciamento de IDs via linha de comando
• n8n API: Operações programáticas com IDs
• UUID Generator: Geradores de UUID online

---

Próximo: Histórico de Workflows - Acesse e analise o histórico de execuções