> ## 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 ao Make via API V4

Guia de uso do app **Econodata** no Make. Permite montar integrações no formato:
**[Gatilho no seu CRM] → [Econodata enriquece] → [Atualiza no CRM/planilha/e-mail]**, sem necessidade de programação.
O código do conector está disponível no repositório **ecdt-ipaas-connectors (packages/make)** e o contrato da integração pode ser consultado em **openapi.yaml**.
Atualmente, o aplicativo está **publicado**, porém com **visibilidade por link de convite**, ainda não listado no catálogo público do Make. Usuários da organização da Econodata conseguem localizar os módulos pesquisando por **Econodata** em um cenário. Para usuários externos, é necessário solicitar o link de instalação ao time responsável.

## Pré-requisitos

Antes de iniciar a configuração, é necessário possuir:
* Uma conta no Make (qualquer plano, pois o aplicativo utiliza uma operação por chamada);
* Uma API Key da Econodata no formato **ek\_live\_...**, com escopo de leitura (preset **"Integração (somente leitura)"**, disponível no painel **Integrações & API v4**);

## 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_1b7tyt3.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 "Make - 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_jxcjf5.png)
## 1. Conectando a conta da Econodata

Adicione qualquer módulo da Econodata a um cenário e clique em **Create a connection**.
Preencha os campos conforme abaixo:
| Campo | Valor |
| ---- |
| API Key | Sua chave **ek\_live\_...** |
| Base URL | Produção: [**https://api.econodata.com.br**](https://api.econodata.com.br)

A autenticação é realizada enviando a chave no cabeçalho:
**Authorization: Bearer {API\_KEY}**
Durante o teste da conexão será realizada uma consulta de saldo. Caso a chave seja válida, a conexão será salva automaticamente. Caso contrário, a conexão será recusada imediatamente.

Segue o passo a passo de como criar um cenário e conectar à Econodata:

1.  Clique em "Create scenario"
![](https://storage.crisp.chat/users/helpdesk/website/-/1/9/2/4/1924e04f5671d600/image_19mrp0j.png)

2. Busque a integração com a Econodata
![](https://storage.crisp.chat/users/helpdesk/website/-/1/9/2/4/1924e04f5671d600/image_1hfds1a.png)

3. Insira a chave de integração criada em "Chaves e integrações"
4. Selecione o endpoint que deseja consumir e está pronto para usar
![](https://storage.crisp.chat/users/helpdesk/website/-/1/9/2/4/1924e04f5671d600/image-35_atzat1.png)
## 2. Módulos disponíveis

Após conectar sua conta, estarão disponíveis os seguintes módulos:
| Módulo | O que faz | Entrada típica |
| ---- |
| Encontrar empresa | Retorna uma empresa por identificador forte | CNPJ, site ou e-mail |
| Match por nome | Busca aproximada por nome (fuzzy) | Nome (+ UF, se houver) |
| Enriquecer lote | Enriquece de 1 a 100 CNPJs em uma única requisição | Lista de CNPJs |
| Buscar decisores | Consulta o organograma paginado | CNPJ + papel |
| Segmentar por filtros | Retorna empresas conforme filtros | Filtros JSON |
| Segmentar por pesquisa salva | Segmenta empresas utilizando uma pesquisa salva | Pesquisa (dropdown) |
| Contar segmento | Retorna apenas a quantidade de empresas | Filtros ou pesquisa salva |
| Listar grupo econômico | Consulta empresas ligadas por sócios | CNPJ |
| Listar pesquisas salvas | Retorna os metadados das pesquisas salvas da conta | — |
| Ver saldo | Consulta o saldo de tokens | — |
| Make an API call | Permite chamar qualquer endpoint da API v4 | Caminho relativo + método |

###### Observação
Os módulos baseados em **pesquisas salvas** apresentam automaticamente um **dropdown dinâmico**, contendo todas as pesquisas compartilhadas disponíveis na conta. Basta selecionar a pesquisa desejada.

## 3. Configurando o enriquecimento de dados

Durante a utilização dos módulos de enriquecimento, é possível definir quais informações serão retornadas.
###### Buckets disponíveis
Cada bucket entregue consome tokens.
Os buckets disponíveis são:
* cadastro (RFB);
* estrategico (porte, faturamento e tecnologias);
* perfilNegocio (setor, matriz e filiais, dívidas);
* contatosBasicos (telefones e e-mails);
* contatosAvancados (contatos verificados, decisores e redes sociais).
Também é possível solicitar apenas campos específicos utilizando **dot-path**, por exemplo:
* cadastro.razaoSocial;
* contatosBasicos.telefones.

Os campos podem ser informados um por linha ou separados por vírgula.
Além disso, existe a configuração **Máximo de itens por lista**, utilizada para definir o número máximo de itens retornados dentro de cada empresa, como telefones e sócios.
Quando informado **0**, todos os itens disponíveis serão retornados.
> **Importante:**
> * Caso nenhum bucket seja selecionado, o lookup retornará apenas o **CNPJ**, sendo esta a opção de menor custo em tokens.
> * O bucket **contatosAvancados** não está disponível nos módulos de Segmentação. Para consultar decisores, utilize o módulo **Buscar decisores**.

## 4. Exemplo de integração

###### Pipedrive → Econodata → Pipedrive
Um fluxo bastante comum consiste em enriquecer dados de empresas no Pipedrive utilizando a Econodata.
O processo funciona da seguinte forma:
1. Configure o gatilho **Watch Deals** ou **Watch Organizations** no Pipedrive;
2. Adicione o módulo **Encontrar empresa** da Econodata;
3. Informe o CNPJ ou o domínio do e-mail do contato;
4. Selecione os buckets desejados, como por exemplo:
    * cadastro;
    * contatosBasicos;
5. Adicione o módulo **Update Deal** ou **Update Organization** do Pipedrive;
6. Faça o mapeamento dos campos retornados pela Econodata (como **Razão Social**, **Faturamento**, **Telefones**, entre outros) para os campos correspondentes no Pipedrive.
Esse mesmo padrão pode ser utilizado com outras ferramentas como:
* HubSpot;
* RD Station;
* Ploomes;
* Google Sheets;
* E-mail;
* entre outras integrações suportadas pelo Make.
###### Onde normalmente está o CNPJ em cada CRM


| CRM | Localização mais comum |
| ---- |
| RD Station CRM | Campo personalizado da organização/empresa |
| Pipedrive | Campo personalizado da organização |
| HubSpot | Propriedade personalizada da empresa (Company) |
| Ploomes | Campo de CNPJ do cliente |
Caso o CRM não armazene o CNPJ, utilize inicialmente o módulo **Match por nome**, informando a razão social e a UF. Após receber o CNPJ retornado pela Econodata, grave esse valor no CRM para que as próximas consultas utilizem **Encontrar empresa**, que oferece maior precisão.

## 5. Paginação e limites

Os módulos de listagem do Make realizam a paginação automaticamente, sem necessidade de controlar cursor ou número de página.
Dois parâmetros controlam o volume de resultados retornados:
| Campo | O que faz |
| ---- |
| Tamanho da página | Define a quantidade de itens por requisição |
| Limite de registros | Define o total máximo de registros retornados durante a execução |
Por padrão, apenas uma página é retornada. Caso necessário, esse limite pode ser aumentado.
Além disso, o próprio Make possui limites por execução:
* Até **50 requisições** de paginação;
* Até **3.200 registros** retornados.

## 6. 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;
* Os módulos de segmentação consomem tokens a cada página retornada;
* Para apenas estimar o tamanho de um segmento, recomenda-se utilizar **Contar segmento**, que consome apenas o custo base do endpoint, sem cobrança por campos, e não recobra a mesma contagem dentro de um período de 24 horas;
* As ações **Ver saldo** e **Listar pesquisas salvas** não consomem tokens;
* Consultas repetidas para a mesma empresa dentro de um período de 24 horas não geram nova cobrança dos dados já cobrados;
* O consumo disponível pode ser acompanhado utilizando o módulo **Ver saldo**.

## 7. Possíveis erros

Durante a utilização da integração, o aplicativo traduz automaticamente os erros retornados pela API, facilitando sua identificação.
Os retornos mais comuns são:
| Status | Significado | O que fazer |
| ---- |
| 401 | Chave inválida ou revogada | Verifique a API Key |
| 402 | Saldo de tokens insuficiente | Recarregue os tokens ou consulte o saldo |
| 403 | A chave não possui o escopo necessário | Utilize uma chave de integração com permissão de leitura |
| 422 | Parâmetro inválido | Revise os dados informados |
| 429 | Rate limit | Aguarde o tempo informado no cabeçalho **Retry-After** |
| 503 | Indisponibilidade temporária | Aguarde alguns instantes e tente novamente |

###### Erros comuns

Algumas situações podem gerar dúvidas durante a configuração:
* **Cannot GET / Cannot POST (404):** normalmente indica que a **Base URL** foi configurada utilizando o endereço da plataforma em vez do endereço da API.
* **Empresa não encontrada no lote:** o CNPJ continua sendo retornado, porém com o campo **Motivo** preenchido (por exemplo: *not\_found*). Basta filtrar os resultados onde o campo Motivo estiver vazio para visualizar apenas as empresas encontradas.
* **Resultado vazio em Segmentar:** geralmente indica que os filtros utilizados estão muito restritivos. Recomenda-se validar primeiro utilizando o módulo **Contar segmento por filtros**.

## Referências

Caso deseje consultar a documentação técnica da integração, utilize os seguintes materiais:
* contratos-novos-endpoints-v4.md — Catálogo de campos por bucket;
* autenticacao-api-key.md — Documentação de autenticação por API Key;
* **Repositório ecdt-ipaas-connectors (packages/make)** — Código-fonte do conector;
* **docs/como-conectar-crm.md** — Guia completo da integração com detalhamento do mapeamento de campos (também utilizado como README da página do aplicativo no Make).

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)".