> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.econodata.com.br/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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)**.
![](https://storage.crisp.chat/users/helpdesk/website/-/1/9/2/4/1924e04f5671d600/image_swxy9y.png)
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.

![](https://storage.crisp.chat/users/helpdesk/website/-/1/9/2/4/1924e04f5671d600/image_1h4aooo.png)
## 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:
| Campo | Valor |
| ---- |
| API Key | Sua chave **ek\_live\_...** |
| Base URL | [**https://api.econodata.com.br**](https://api.econodata.com.br/) |

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**;

![](https://storage.crisp.chat/users/helpdesk/website/-/1/9/2/4/1924e04f5671d600/image-37_18xxh9p.png)

2. Selecione o recurso **Empresa**;
![](https://storage.crisp.chat/users/helpdesk/website/-/1/9/2/4/1924e04f5671d600/image-36_1p97vr7.png)

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:
| Operação | O que faz |
| ---- |
| Encontrar Empresa | Retorna uma empresa por CNPJ, site ou e-mail |
| Match por Nome | Busca aproximada (fuzzy) por nome |
| Enriquecer Lote | Enriquece uma lista de 1 a 100 CNPJs |
| Segmentar por Filtros | Lista empresas conforme filtros (porte, UF, CNAE, faturamento, entre outros) |
| Segmentar por Pesquisa Salva | Segmenta empresas utilizando uma pesquisa salva |
| Contar Segmento por Filtros | Retorna apenas a quantidade de empresas de um segmento |
| Contar Segmento por Pesquisa Salva | Retorna apenas a contagem baseada em uma pesquisa salva |
| Grupo Econômico | Lista empresas ligadas por sócios |
| Listar Pesquisas Salvas | Retorna as pesquisas salvas compartilhadas da conta |
| Buscar Decisores | Consulta o organograma de decisores ou colaboradores |

###### Recurso Conta
Também está disponível o seguinte recurso:
| Operação | O que faz |
| ---- |
| Ver Saldo | Consulta o saldo de tokens da conta |


## 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:
| Status | Significado | O que fazer |
| ---- |
| 401 | Chave inválida, revogada ou expirada | Verifique a API Key ou gere uma nova chave |
| 402 | Saldo de tokens insuficiente | Recarregue os tokens ou consulte o saldo utilizando **Ver Saldo** |
| 403 | A chave não possui o escopo necessário | Utilize uma chave com a permissão adequada para a operação |
| 422 | Parâmetro inválido | Revise os dados informados, como CNPJ ou filtros |
| 429 | Rate limit excedido | Aguarde o tempo informado no cabeçalho **Retry-After** antes de tentar novamente |
| 503 | Indisponibilidade temporária | Tente novamente ou utilize a opção **Retry On Fail** do node |

###### 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__](mailto:suporte@econodata.com.br)".