Package Information
Documentation
n8n-nodes-blocos
Este é um pacote de nós da comunidade do n8n. Com ele você usa a Blocos Marketing nos seus fluxos do n8n.
A Blocos Marketing é uma plataforma para agências de marketing: reúne os dados de mídia e de análise de cada negócio dos clientes (Meta Ads, Google Ads, Google Analytics, Search Console e mais), conduz planos de ação aprovados pelo cliente e publica relatórios num portal do cliente.
O n8n é uma plataforma de automação de fluxos com licença fair-code.
Instalação ·
Manter nas atualizações do n8n ·
Operações ·
Gatilho ·
Credenciais ·
Compatibilidade ·
Uso ·
Recursos
Instalação
No n8n, abra Settings › Community Nodes › Install (só o dono e os administradores veem essa tela), digite n8n-nodes-blocos, marque a caixa que aceita os riscos de código de fonte pública e clique em Install. O passo a passo oficial está no guia de instalação do n8n.
Este pacote é para o n8n próprio (self-hosted). A interface está em português, e o n8n Cloud só instala nós verificados pelo n8n, o que exige interface em inglês. Se você usa o n8n Cloud, avise a Blocos: o pacote em inglês sai quando houver quem precise dele.
A interface do próprio n8n continua em inglês ("Execute step", "Credentials"…): só o conteúdo dos nós da Blocos está em português. A exceção é o campo Events do gatilho: é o nome que o editor do n8n exige para listar os eventos no painel de nós.
Manter o pacote nas atualizações do n8n
No n8n em Docker (Easypanel, Portainer, Coolify, docker compose…), os pacotes da comunidade ficam em /home/node/.n8n/nodes, dentro do container. Se essa pasta não estiver num volume, cada atualização ou reinício recria o container e o pacote some (o banco do n8n continua lembrando dele e avisa que está faltando).
Antes de tudo: confira se a variável N8N_ENCRYPTION_KEY está definida. Sem ela, a chave que protege as credenciais mora em /home/node/.n8n/config; copie o valor de encryptionKey desse arquivo para a variável antes de montar o volume, ou as credenciais salvas deixam de abrir.
- Volume em
/home/node/.n8n. No serviço do n8n, monte um volume nesse caminho e implante (no Easypanel: Armazenamento › Adicionar Montagem de Volume). Em modo fila (editor, webhook e worker), faça em cada serviço, com um volume para cada um: cada serviço instala o pacote no próprio disco. - Reinstalação automática. Acrescente
N8N_REINSTALL_MISSING_PACKAGES=trueàs variáveis de ambiente de cada serviço. Ao iniciar, o n8n reinstala do npm, na mesma versão, todo pacote que o banco lembra e que não está no disco. - Confira. Implante de novo sem mudar nada e veja em Settings › Community Nodes se o
n8n-nodes-blocoscontinua lá.
Na hora de atualizar o n8n:
- Faça um backup do banco do n8n antes: as migrações de uma versão nova não voltam atrás só trocando a imagem.
- Use uma versão fixa na imagem (por exemplo
n8nio/n8n:2.46.0), nuncalatest, e suba uma versão por vez, lendo as notas de lançamento. - Em modo fila, editor, webhook e worker precisam rodar a mesma versão: atualize o editor primeiro (ele aplica as migrações) e os outros logo em seguida.
- Depois, confira Settings › Community Nodes e rode um nó da Blocos. Se o pacote sumir, implante o serviço de novo: a reinstalação automática age ao iniciar.
Atualizar o próprio pacote da Blocos é o botão Update em Settings › Community Nodes, quando sai uma versão nova.
Operações
O nó Blocos Marketing usa a API REST da Blocos (/api/v1). Toda operação roda com as permissões da chave de API.
| Recurso | Operações |
|---|---|
| Cliente | Atualizar, Criar, Excluir, Obter, Obter vários |
| Métrica | Consultar, Obter retrato completo, Obter série diária, Obter vários (catálogo de métricas), Obter visão geral |
| Negócio | Atualizar, Criar, Excluir, Obter, Obter vários |
| Plano de ação | Criar, Enviar ao cliente, Obter, Obter vários, Registrar resultado |
| Relatório | Criar, Liberar no portal, Obter, Obter vários, Publicar versão |
| Tarefa | Adicionar itens ao checklist, Atualizar, Criar, Criar comentário, Excluir, Obter, Obter vários |
Os nomes são os da interface da Blocos: negócio é a empresa que paga pela mídia, e tarefa é a tarefa de Planejamentos.
Observações:
- As operações Obter vários têm Retornar todos: a Blocos entrega os resultados de 100 em 100.
- Métrica › Consultar, Obter visão geral e Obter retrato completo calculam as razões (CPA, CTR, ROAS) sobre as somas, como o painel faz, e comparam com o período anterior. Contas em moedas diferentes nunca são somadas.
- Tarefa › Atualizar movendo um plano de ação aprovado para a etapa de concluído registra o resultado do plano, como na interface da Blocos.
- As etapas e as prioridades das tarefas, e a lista de métricas, vêm da sua agência, inclusive as personalizadas.
Gatilho
O nó Blocos Marketing Trigger inicia um fluxo quando algo acontece na Blocos: uma tarefa é criada ou concluída, um cliente aprova um plano de ação ou abre um relatório, um formulário é respondido, a sincronização diária termina, uma conexão cai e mais. Escolha Todos os eventos para receber também os eventos que a Blocos criar depois. Os nomes dos eventos são os mesmos de Desenvolvedores › Webhooks na Blocos. No painel de nós do n8n, cada evento aparece como uma opção ("Quando uma tarefa for concluída"…), que cria o gatilho com o evento já marcado.
- Ativar o fluxo registra um webhook na Blocos (Configurações › Desenvolvedores › Webhooks); desativar remove o webhook.
- Toda entrega é assinada. O gatilho confere o cabeçalho
X-Webhook-Signature(HMAC-SHA256 de<timestamp>.<corpo>com o segredo do webhook) e recusa entregas com mais de cinco minutos. A requisição que não passa na conferência recebe401e nunca inicia o fluxo. - A Blocos só entrega em endereços públicos. Se o n8n roda no seu computador, exponha-o e defina a variável de ambiente
N8N_WEBHOOK_URLdo n8n (WEBHOOK_URLantes do n8n 2.x) com o endereço público. - A Blocos tenta de novo as entregas que falham e desliga o webhook depois de 50 falhas seguidas. Para voltar a receber eventos, desative e ative o fluxo: o gatilho remove o webhook antigo e registra um novo. Desligar o webhook na Blocos interrompe as entregas, mas ativar o fluxo de novo liga o webhook outra vez; para parar de vez, desative o fluxo no n8n.
Cada entrega vira um item:
{
"id": "id da entrega",
"event": "task.completed",
"agency_id": "…",
"occurred_at": "2026-10-28T13:05:00.000Z",
"data": { "id": "…", "title": "Revisar os criativos da campanha", "status": "concluido" }
}
data é o registro que mudou. Formulário respondido traz os dados pessoais que a pessoa digitou (nome, e-mail, respostas).
Credenciais
Você precisa de uma chave de API da Blocos.
- Na Blocos, abra Configurações › Desenvolvedores › Chaves de API.
- Crie uma chave. Escolha acesso de escrita se o fluxo cria ou altera alguma coisa; uma chave só de leitura usa apenas as operações de leitura.
- Copie a chave (ela começa com
ak_). A Blocos mostra a chave uma única vez. - No n8n, crie uma credencial Blocos Marketing API e cole a chave. Mantenha a URL base padrão (
https://app.blocosmarketing.com).
A chave age com o cargo de quem a criou: uma operação que o cargo não pode fazer falha com 403. O gatilho precisa de uma chave de escrita cujo cargo tenha a permissão Gerenciar API, webhooks e apps conectados (MCP). Se essa pessoa sair da agência, a chave deixa de funcionar.
Crie a chave com alguém que enxergue a agência inteira. A chave feita por um membro com a carteira de clientes recortada é recusada com 403 portfolio_restricted, e um webhook criado antes da restrição é desligado.
Compatibilidade
Testado com o n8n 2.45.5.
Uso
Enviar cada novo formulário para o chat da equipe. Blocos Marketing Trigger (evento: Formulário respondido) → Slack.
Criar uma tarefa quando o cliente pedir ajustes num relatório. Blocos Marketing Trigger (evento: Cliente pediu ajustes no relatório) → Blocos Marketing (Tarefa › Criar). O evento traz o relatório em {{ $json.data.subject_id }}, o título dele em {{ $json.data.payload.title }}, o comentário do cliente em {{ $json.data.payload.comment }} e o negócio em {{ $json.data.business_id }}.
Números da semana numa planilha. Schedule Trigger → Blocos Marketing (Métrica › Consultar, período Últimos 7 dias) → Google Sheets.
Perguntar a um agente de IA sobre um cliente. O nó Blocos Marketing pode ser usado como ferramenta pelo AI Agent do n8n: dê a ele Métrica › Obter retrato completo para o agente ler todas as fontes de um negócio.
Os erros da Blocos chegam com um código e uma mensagem, por exemplo 422 quando uma etapa de tarefa não existe na agência. Ligue a configuração On Error › Continue do nó para o fluxo seguir e você tratar o item de erro.
Recursos
- Documentação dos nós da comunidade do n8n
- Blocos Marketing
- Referência da API da Blocos:
https://app.blocosmarketing.com/api/v1/openapi.json