Como conectar a Econodata no n8n via API V4

Guia de uso do node n8n-nodes-econodata. Permite utilizar os recursos de enriquecimento e segmentação de empresas B2B da API pública v4 da Econodata diretamente em seus fluxos do n8n.
Nesta primeira versão, o node funciona apenas no sentido de consulta de dados (read-only). Ou seja, ele permite buscar informações da Econodata para utilizar em automações envolvendo CRM, planilhas, e-mails e outros sistemas, mas não realiza gravação de dados na Econodata nem possui gatilhos (triggers) ou polling.

Pré-requisitos

Antes de iniciar a configuração, é necessário possuir:

• Uma instância do n8n, seja self-hosted (Docker ou npm) ou n8n Cloud;
• Os Community Nodes habilitados (no self-host normalmente já vêm habilitados; em alguns ambientes gerenciados pode ser necessário ativá-los nas configurações);
• Uma API Key da Econodata no formato ek_live_..., gerada no painel Integrações & API v4 da plataforma;
• Para automações, recomenda-se utilizar uma chave criada com o preset "Integração (somente leitura)".

Instalando o node

Existem duas formas de instalar o node da Econodata.

Instalação pela interface do n8n

No menu do n8n, acesse:
Settings → Community Nodes → Install

Em seguida:

1. Informe o pacote n8n-nodes-econodata;
2. Clique em Install.

Após a instalação, o node Econodata ficará disponível na busca de nodes do editor.

Instalação manual (Self-host)

Caso utilize uma instalação própria do n8n, também é possível instalar manualmente executando o comando:

npm install n8n-nodes-econodata

Após a instalação, reinicie o serviço do n8n.

Como gerar sua chave de API

Antes de conectar a Econodata a qualquer integração, você precisa gerar uma chave de API dentro da plataforma.

1. Acesse Chaves e Integrações

Clique no seu perfil, no canto superior direito da plataforma, e selecione "Chaves e integração". Você será direcionado à tela Integrações & API (API V4).

2. Crie a chave

Na aba Chaves API, clique em "+ Criar nova chave". Nessa tela você pode:

• Dar um nome à chave (recomendamos algo identificável, como "n8n - Prospecção", para facilitar o controle de quem usa o quê);
• Selecionar "Gerar chave";
• Copiar a chave gerada no formato ek_live_… (ela só é exibida uma vez, então salve-a em local seguro).

Nessa mesma tela você acompanha, em tempo real:

• Saldo de créditos disponível na conta;
• Chaves ativas (e quantas foram revogadas);
• Integrações vinculadas às suas chaves.

3. Vincule a chave a um conector

Na aba Conectores, você encontra cards para Zapier, Make, n8n, além de API personalizada e MCP · Agentes de IA (em breve). Clique em "Vincular" no conector desejado para associar uma chave já existente a essa integração — assim você mantém visibilidade de quantas chaves ativas cada ferramenta está usando.

Criando a credencial

Ao adicionar o node Econodata pela primeira vez, será necessário criar uma credencial do tipo Econodata API.
Preencha os campos conforme abaixo:

A autenticação é realizada automaticamente utilizando o cabeçalho:
Authorization: Bearer {API_KEY}
A mesma credencial poderá ser reutilizada em diferentes nodes e fluxos.

Criando sua primeira automação

Encontrar Empresa

Uma forma simples de começar é utilizando a operação Encontrar Empresa.
O processo funciona da seguinte forma:

1. Adicione o node Econodata;

2. Selecione o recurso Empresa;

3. Escolha a operação Encontrar Empresa;
4. Selecione a credencial criada anteriormente;
5. Informe um identificador da empresa, como o CNPJ (com ou sem máscara);
6. Opcionalmente, em Incluir, selecione um ou mais buckets para enriquecer os dados (por exemplo, cadastro);
7. Execute o fluxo.

Caso nenhum bucket seja selecionado, será retornado apenas o CNPJ.
Quando um ou mais buckets forem informados, a resposta incluirá os dados correspondentes às categorias selecionadas.
A saída do node poderá ser conectada diretamente aos próximos passos do fluxo, como CRM, planilhas, e-mails ou qualquer outro node do n8n.

Operações disponíveis

Recurso Empresa

Após configurar a credencial, estarão disponíveis as seguintes operações:

Recurso Conta

Também está disponível o seguinte recurso:

Configurando o enriquecimento de dados

O retorno das informações pode ser personalizado através de algumas configurações.

Buckets disponíveis

Cada bucket entregue consome tokens.
Os buckets disponíveis são:

• cadastro (dados cadastrais da Receita Federal);
• estrategico (porte, faturamento, headcount e tecnologias);
• perfilNegocio (setor, matriz, filiais, dívidas e NCM);
• contatosBasicos (telefones e e-mails);
• contatosAvancados (telefones verificados, redes sociais e score).

Caso nenhum bucket seja selecionado, o retorno conterá apenas o CNPJ, sendo esta a opção de menor custo.

Campos (dot-path)

Também é possível solicitar apenas campos específicos utilizando dot-path, como por exemplo:

• cadastro.razaoSocial;
• contatosBasicos.telefones.

Ao solicitar um campo específico, o bucket correspondente será incluído automaticamente.

Escopo

Na operação Encontrar Empresa, também é possível definir o escopo da consulta:

• unidade (padrão);
• filiais;
• matrizFiliais.

Limite

O parâmetro Limite define o número máximo de itens retornados em listas como telefones, sócios e decisores.
Quando informado 0, todos os itens disponíveis serão retornados.

Consumo de tokens

O consumo ocorre com base no endpoint utilizado e na quantidade de informações retornadas por empresa.
Na prática:

• Lookups sem buckets possuem baixo consumo;
• Cada bucket adicional entregue aumenta o consumo de tokens;
• As operações de segmentação consomem tokens a cada chamada realizada;
• Caso seja necessário apenas saber o tamanho de um segmento, recomenda-se utilizar Contar Segmento, que retorna apenas a quantidade de empresas e possui menor custo;
• Consultas repetidas para a mesma empresa dentro de um período de 24 horas não geram nova cobrança dos dados já cobrados;
• Todas as respostas retornam o cabeçalho X-Tokens-Charged, indicando a quantidade de tokens consumidos na operação;
• O consumo disponível pode ser acompanhado utilizando a operação Ver Saldo.

Possíveis erros

Durante a utilização do node, podem ocorrer os seguintes retornos:

Observação

Ao processar listas ou lotes de empresas, recomenda-se habilitar a opção Continue On Fail no node. Dessa forma, caso um item apresente erro, o restante do fluxo continuará sendo executado normalmente.

Se você quer aperfeiçoar o uso da Econodata, entre em contato com o suporte no email "suporte@econodata.com.br".

Actualizado em: 06/08/2026