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

Guia de uso do app **Econodata API v4** no Zapier. Permite montar integrações no formato:
${color}[#e70404]([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/zapier)** e o contrato da integração pode ser consultado em **openapi.yaml**.
Atualmente, o aplicativo está em **beta privado**, ou seja, ainda não está listado no App Directory público do Zapier. O acesso é realizado por convite durante esta fase. Para obter o link de acesso, entre em contato com o time responsável. Após a publicação oficial, o aplicativo poderá ser encontrado normalmente na busca de aplicativos do Zapier.

## Pré-requisitos

Antes de iniciar a configuração, é necessário possuir:
* Uma conta no Zapier;
* 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**);
* Para testes, recomenda-se utilizar a base de **HML**.

## 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_ncwoez.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 "Zapier - 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_5bg3rv.png)
## 1. Conectando a conta da Econodata

Ao adicionar a Econodata em um novo Zap, será necessário criar uma conexão com sua conta.
Preencha os campos conforme abaixo:
| Campo | Valor |
| ---- |
| API Key | Sua chave **ek\_live\_...** |
| Ambiente | Produção (**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á executada uma requisição para consulta de saldo. Caso a chave seja válida, será exibido o rótulo:
**Econodata (N tokens)**

Segue o passo a passo para a criação de um Zap, diretamente do Zapier:
1.  Clique em "Create"
![](https://storage.crisp.chat/users/helpdesk/website/-/1/9/2/4/1924e04f5671d600/image_gbst08.png)

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

3. Insira a chave
4. Integração pronta, com a ajuda do copilot é possível buscar os endpoints disponíveis
![](https://storage.crisp.chat/users/helpdesk/website/-/1/9/2/4/1924e04f5671d600/image_sgkpfs.png)
## 2. Ações disponíveis (Searches)

Após conectar sua conta, estarão disponíveis as seguintes ações:
| Ação | O que faz | Entrada típica |
| ---- |
| Encontrar Empresa | Retorna uma empresa por identificador forte | CNPJ, site ou e-mail |
| Match por Nome | Busca aproximada (fuzzy) por nome | 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 |
| Grupo Econômico | Consulta empresas ligadas por sócios | CNPJ |
| Ver Saldo | Consulta o saldo de tokens | — |

###### Observação
As ações baseadas 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 o uso das ações 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**, como por exemplo:
* cadastro.razaoSocial
* contatosBasicos.telefones
Além disso, existe a configuração **Limite por lista**, utilizada para definir o número máximo de itens retornados em listas como telefones e sócios.
Quando informado **0**, todos os itens disponíveis serão retornados.
Caso nenhum bucket seja selecionado, o lookup retornará apenas o **CNPJ**, sendo esta a opção de menor custo em tokens.

## 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 **Deal Updated** ou **New Deal** no Pipedrive;
2. Adicione a ação **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 a ação **Update Deal** ou **Update Organization** no Pipedrive;
6. Faça o mapeamento dos campos retornados pela Econodata (como cadastro.razaoSocial, estrategico.porte e telefones) para os campos correspondentes no Pipedrive.
Esse mesmo padrão pode ser utilizado com outras ferramentas como:
* HubSpot;
* RD Station;
* Google Sheets;
* E-mail;
* entre outras integrações suportadas pelo Zapier.

## 5. 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 ações de segmentação consomem tokens a cada chamada realizada;
* Caso seja necessário apenas conhecer o tamanho de um segmento, recomenda-se utilizar **Contar Segmento**, que 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;
* O consumo disponível pode ser acompanhado utilizando a ação **Ver Saldo**.

## 6. Possíveis erros

Durante a utilização da integração, podem ocorrer os seguintes retornos:
| 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 | O Zapier realiza backoff automaticamente e tenta novamente. O reenvio não gera nova cobrança |
| 503 | Indisponibilidade temporária | Aguarde alguns instantes e tente novamente |

Caso deseje consultar a documentação técnica da integração, utilize os seguintes materiais:
* **openapi.yaml** — Contrato da API (Produção e HML);
* 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/zapier)** — Código-fonte do conector.

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