# Como enriquecer uma planilha de CNPJs com o telefone e o e-mail dos sócios

> Versão em Markdown de https://datax.plus/guias/enriquecer-planilha-cnpj-api/

Você tem uma lista de empresas e quer saber como falar com os sócios. Este guia mostra como preparar a planilha, calcular o consumo e rodar um script pronto, que pode parar e continuar sem pagar duas vezes pelo mesmo CNPJ.

Por [Equipe DataX](https://datax.plus/) · Publicado em 4 de novembro de 2026 · 8 min de leitura

Resposta curta

Exporte a planilha como CSV, com uma coluna `cnpj`, e rode o script deste guia com a sua chave de API. Para cada CNPJ, ele chama `POST /v1/empresas/{cnpj}/socios` e grava uma linha por sócio, com nome, qualificação, telefones e e-mails, num CSV que abre no Excel. Se parar no meio, é só rodar de novo: os CNPJs já consultados são pulados. A consulta consome 1 requisição por sócio retornado.

## 1. Prepare a lista

- **Salve como CSV.** No Excel, use "Salvar como" e escolha CSV UTF-8. No Google Sheets, use "Fazer download" e depois "Valores separados por vírgula". O script aceita vírgula ou ponto e vírgula.
- **Crie uma coluna chamada `cnpj`.** As outras colunas são ignoradas. O CNPJ pode ter pontos, barra e traço, porque o script limpa. O CNPJ alfanumérico também funciona: o script mantém as letras.
- **Cuidado com os zeros à esquerda.** O Excel costuma tratar CNPJ como número e apagar os zeros do começo. O script completa de volta para 14 caracteres, mas, se a coluna aparecer em notação científica, como `1,12E+13`, os números já foram perdidos: volte ao arquivo original e formate a coluna como texto.
- **Pode deixar os repetidos.** O script consulta cada CNPJ uma vez só.

```
empresa,cnpj
Exemplo Tecnologia,11.222.333/0001-81
Exemplo Comércio,44.555.666/0001-99
```

## 2. Calcule o consumo

A consulta de sócios está no teste grátis e nos planos Intermediário e Avançado. Ela consome 1 requisição do limite diário por sócio retornado, então o total depende da sua lista. Para estimar, rode antes com os 10 primeiros CNPJs e veja a média de sócios por empresa. A tabela usa 2 como exemplo.

| Tamanho da lista | Consumo | Tempo mínimo no script | Plano |
| --- | --- | --- | --- |
| 10 empresas | 20 requisições | 5 segundos | Teste grátis (20 chamadas) |
| 1.000 empresas | 2.000 requisições | 8 minutos | Intermediário, em um dia |
| 5.000 empresas | 10.000 requisições | 42 minutos | Intermediário, em dois dias, ou Avançado, em um |
| 20.000 empresas | 40.000 requisições | 2 horas e 50 minutos | Avançado, em dois dias |

No limite por minuto, cada CNPJ conta 1, não importa quantos sócios volte. O tempo mínimo considera só a pausa de meio segundo entre as chamadas: o tempo real é maior, porque soma o tempo de resposta de cada consulta. Se você chegar ao limite do dia, o script para, e você continua no dia seguinte.

## 3. Rode o script

Você precisa do Python 3 e da biblioteca `requests` (`pip install requests`). Salve o script abaixo como `enriquecer.py`, na mesma pasta do `empresas.csv`, e rode:

```bash
# No Windows (PowerShell)
$env:DATAX_KEY = "SUA_CHAVE"
python enriquecer.py

# No macOS ou Linux
export DATAX_KEY="SUA_CHAVE"
python3 enriquecer.py
```

```python
"""Completa uma lista de CNPJs com o telefone e o e-mail dos sócios.

Lê empresas.csv (com uma coluna "cnpj") e grava socios.csv, uma linha por sócio.
Se parar no meio, rode de novo: os CNPJs já consultados são pulados.
"""
import csv
import os
import re
import sys
import time
from datetime import date
from pathlib import Path

import requests

API = "https://api.datax.plus"
HEADERS = {"api-key": os.environ["DATAX_KEY"]}
ENTRADA = Path("empresas.csv")
SAIDA = Path("socios.csv")
PAUSA = 0.5  # 120 chamadas por minuto, o limite do plano Intermediário
COLUNAS = ["cnpj", "nome", "qualificacao", "telefones", "emails", "consultado_em", "observacao"]

def ler_cnpjs():
    with ENTRADA.open(encoding="utf-8-sig", newline="") as f:
        inicio = f.read(2048)
        f.seek(0)
        separador = ";" if inicio.count(";") > inicio.count(",") else ","
        linhas = csv.reader(f, delimiter=separador)
        cabecalho = [c.strip().lower() for c in next(linhas)]
        if "cnpj" not in cabecalho:
            sys.exit('O arquivo empresas.csv precisa de uma coluna chamada "cnpj".')
        coluna = cabecalho.index("cnpj")
        cnpjs = {}
        for linha in linhas:
            valor = linha[coluna] if len(linha) > coluna else ""
            limpo = re.sub(r"[^0-9A-Za-z]", "", valor).upper()
            if limpo:
                cnpjs[limpo.zfill(14)] = True
    return list(cnpjs)

def ja_consultados():
    if not SAIDA.exists():
        return set()
    with SAIDA.open(encoding="utf-8-sig", newline="") as f:
        return {linha["cnpj"] for linha in csv.DictReader(f, delimiter=";")}

def main():
    r = requests.get(f"{API}/v1/plano/limite", headers=HEADERS, timeout=30)
    r.raise_for_status()
    plano = r.json()
    print(f"Plano {plano['planoNome']}: {plano['consumoDia']} de {plano['limiteDiario']} usadas hoje")

    feitos = ja_consultados()
    pendentes = [c for c in ler_cnpjs() if c not in feitos]
    print(f"{len(pendentes)} CNPJs para consultar, {len(feitos)} já consultados")

    arquivo_novo = not SAIDA.exists()
    consumo = 0
    with SAIDA.open("a", encoding="utf-8-sig", newline="") as f:
        saida = csv.writer(f, delimiter=";")
        if arquivo_novo:
            saida.writerow(COLUNAS)
        hoje = date.today().isoformat()

        for cnpj in pendentes:
            r = requests.post(f"{API}/v1/empresas/{cnpj}/socios", headers=HEADERS, timeout=60)

            if r.status_code in (404, 422):
                saida.writerow([cnpj, "", "", "", "", hoje, f"recusado pela API ({r.status_code})"])
            elif r.status_code == 200:
                dados = r.json()
                consumo += dados.get("unidadesConsumidas", 0)
                socios = dados.get("socios") or []
                if not socios:
                    saida.writerow([cnpj, "", "", "", "", hoje, "nenhum sócio retornado"])
                for s in socios:
                    saida.writerow([
                        cnpj,
                        s.get("nome"),
                        s.get("qualificacao"),
                        " | ".join(s.get("telefones") or []),
                        " | ".join(s.get("emails") or []),
                        hoje,
                        "",
                    ])
            else:
                print(f"Parando em {cnpj}: {r.status_code} {r.text[:200]}")
                print(f"Consumo desta rodada: {consumo}. Rode de novo depois de resolver.")
                sys.exit(1)

            f.flush()
            time.sleep(PAUSA)

    print(f"Pronto. Consumo desta rodada: {consumo}.")

if __name__ == "__main__":
    main()
```

No plano Avançado, com 300 chamadas por minuto, você pode reduzir `PAUSA` para `0.2`.

## 4. Abra o resultado

O arquivo `socios.csv` abre direto no Excel, com separador de ponto e vírgula. Cada sócio vira uma linha:

| Coluna | O que traz |
| --- | --- |
| `cnpj` | CNPJ consultado |
| `nome` | Nome do sócio |
| `qualificacao` | Papel na empresa, como Sócio-Administrador |
| `telefones` | Telefones encontrados, separados por `\|` |
| `emails` | E-mails encontrados, separados por `\|` |
| `consultado_em` | Data da consulta |
| `observacao` | Preenchida quando nenhum sócio voltou ou a API recusou o CNPJ |

Para começar pelos contatos mais úteis, filtre pela [qualificação](https://datax.plus/guias/qsa-cnpj-quadro-societario-api/): sócios-administradores e administradores costumam responder pela empresa. O script não grava o CPF de propósito: se você não vai usar um dado pessoal, é melhor não guardá-lo.

## Se algo der errado

| O que aparece | O que significa | O que fazer |
| --- | --- | --- |
| `KeyError: 'DATAX_KEY'` | A variável com a chave não foi definida neste terminal | Defina a variável e rode de novo |
| O arquivo precisa de uma coluna chamada `cnpj` | O nome da coluna é outro | Renomeie a coluna |
| `401` | Chave ausente, inválida ou com formato errado | Gere uma chave no portal |
| `403` | A consulta não está no seu plano. O plano Entrada não inclui empresas | Veja os [planos](https://datax.plus/#planos) |
| Outra recusa, parando no meio | Pode ser o limite do minuto ou do dia, ou uma instabilidade | Rode de novo mais tarde: o script continua de onde parou |

## Outras formas de fazer

| Forma | Bom para | Limitação |
| --- | --- | --- |
| Script deste guia | Listas de qualquer tamanho, de uma vez só | Precisa rodar Python |
| [n8n, Make ou Zapier](https://datax.plus/guias/enriquecer-crm-n8n-make-zapier/) | Fluxo sem código, inclusive a partir do Google Sheets ou do CRM | Cada ferramenta tem o próprio limite de execuções |
| [Agente de IA com MCP](https://datax.plus/guias/mcp-agente-ia-consultar-cpf-cnpj/) | Listas pequenas, com ajuda para limpar e resumir | Os dados passam pela ferramenta de IA |
| [Lote misto](https://datax.plus/api-lote-cpf-cnpj/) | Sistemas que recebem webhook, com até 100 itens por pedido | Só no plano Avançado |
| [Consulta no portal](https://datax.plus/#portal) | Poucas empresas, sem programar | Manual: não serve para listas grandes |

## Boas práticas

- Comece com uma amostra pequena, para confirmar o formato e medir o consumo.
- Filtre a lista antes: empresas fora do seu perfil só consomem o limite.
- Guarde o resultado em local protegido, porque o arquivo contém dados pessoais, e apague o que não for usar.
- Atualize de tempos em tempos: o campo `consultado_em` mostra a idade de cada contato.
- Use os contatos com uma finalidade legítima e clara, ofereça a opção de sair da lista e evite disparos em massa. Na dúvida sobre a LGPD no seu caso, fale com o seu jurídico.

## Dúvidas sobre enriquecer uma planilha de CNPJs

### Preciso saber programar para enriquecer a planilha?

Para este script, basta instalar o Python e rodar alguns comandos no terminal, sem alterar o código. Se preferir não usar o terminal, o mesmo resultado sai em ferramentas sem código, como [n8n, Make ou Zapier](https://datax.plus/guias/enriquecer-crm-n8n-make-zapier/). Para poucas empresas, dá para consultar direto no [portal](https://datax.plus/#portal), sem programar.

### Quanto custa enriquecer uma lista de CNPJs?

Cada sócio retornado consome 1 requisição do limite diário. Uma lista de 1.000 empresas com 2 sócios em média consome 2.000 requisições, que cabem em um dia do plano Intermediário (R$ 299/mês, 5.000 por dia). Para testar, o período grátis de 24 horas tem 20 chamadas, sem cartão.

### O que acontece se o limite do dia acabar?

A API recusa as chamadas seguintes e o script para, mostrando a resposta. O que já foi consultado fica salvo em socios.csv. No dia seguinte, rode de novo: ele pula os CNPJs já consultados e continua.

### Vou pagar duas vezes se rodar o script de novo?

Não pelos CNPJs que já estão em socios.csv, porque o script os pula. Se você apagar esse arquivo, ele consulta tudo de novo.

### Por que algumas empresas voltam sem contato?

Nem todo sócio tem contato encontrado, e empresas em que todos os sócios são pessoas jurídicas podem voltar sem ninguém, porque a consulta devolve os sócios pessoa física.

### A planilha funciona no Google Sheets?

Sim. Baixe a planilha como CSV, rode o script e importe o socios.csv de volta. Para enriquecer direto na planilha, use uma ferramenta de automação como n8n, Make ou Zapier.

## Teste com os primeiros CNPJs da sua lista, grátis por 24 horas e sem cartão.

[Começar teste grátis](https://portal.datax.plus/auth/cadastro) [Ver a API de sócios](https://datax.plus/api-socios-cnpj/)