API EvoDATA

Começando

Todos os recursos vivem sob um único host, em uma versão fixada no caminho. Não há SDK: qualquer cliente HTTP serve.

Primeira chamada

curl "https://evodata.app/api/v1/empresas?uf=DF&situacao=02&por_pagina=1"

Autenticação

Existem dois regimes, conforme a sensibilidade do dado:

Obtendo a chave

Emita em Chaves de API, no painel. A chave em claro aparece uma única vez, no momento da criação: o sistema guarda apenas um SHA-256, então nem o suporte consegue recuperá-la. Perdeu, revogue e emita outra. Cada conta pode manter até 5 chaves ativas — use uma por integração, para poder revogar uma sem derrubar as demais.

Enviando a chave

curl -H "Authorization: Bearer evd_SUA_CHAVE" \
  "https://evodata.app/api/v1/pessoas?nome=MARIA&uf=SP"

O cabeçalho X-API-Key é aceito como alternativa. A chave não é lida da query string, de propósito: parâmetro de URL vaza em log de servidor, histórico de navegador e cabeçalho Referer.

Recusas possíveis

Limites de uso

O custo real de cada chamada é uma consulta em um PostgreSQL de ~118 GB compartilhado com outro sistema em produção. O limite protege o banco, não o servidor de aplicação.

Cabeçalhos em toda resposta

Convenções

Listas

Parâmetros marcados como lista aceitam duas formas equivalentes. Valores repetidos são deduplicados e a ordem é irrelevante.

?uf=SP,RJ,MG          # separados por vírgula
?uf[]=SP&uf[]=RJ      # repetindo a chave

Valores fora do domínio

Filtros com domínio fechado — uf, situacao, porte, size_class, buscar_em, ordenar — descartam em silêncio o que não reconhecem, em vez de devolver erro. Uma UF digitada errado simplesmente não filtra. Se a lista inteira for inválida, o padrão do campo volta a valer.

Booleanos

Campos boolean ativam com 1, true, on ou yes; qualquer outra coisa desativa. Os campos marcados boolean³ são ternários: aceitam 1/true/S para sim, 0/false/N para não, e tratam a ausência como “indiferente”, que é diferente de “não”.

Números e datas

Valores monetários aceitam ponto ou vírgula decimal: 1500.50 e 1.500,50 chegam ao mesmo lugar. Datas usam AAAA-MM-DD e passam por validação de calendário — 2025-02-30 é descartada silenciosamente.

Buscar empresas

GET https://evodata.app/api/v1/empresas

Busca paginada sobre estabelecimentos. Ao menos um filtro é obrigatório — uma consulta irrestrita sobre dezenas de milhões de linhas não é atendida e devolve 422.

Parâmetros

Identificação

Localização

Atividade econômica

Situação e porte

Presença de contato

Enriquecimento

Paginação e ordenação

Resposta

{
  "dados": [ { /* objeto Empresa, ver abaixo */ } ],
  "paginacao": {
    "pagina": 1,
    "por_pagina": 25,
    "total": 482163,
    "total_exato": false,
    "tem_proxima": true
  },
  "avisos": []
}

avisos é um array de strings. Hoje ele só recebe uma mensagem, quando a ordenação pedida em ordenar foi descartada: classificar um conjunto muito grande faz o planejador trocar o índice correto por uma varredura ordenada da tabela inteira. Nesse caso os resultados voltam na ordem natural do índice e a requisição segue sendo 200.

Objeto Empresa

Exemplo

curl -G "https://evodata.app/api/v1/empresas" \
  --data-urlencode "uf=SP,RJ" \
  --data-urlencode "cnae=4721102" \
  --data-urlencode "abertura_de=2024-01-01" \
  --data-urlencode "com_email=1" \
  --data-urlencode "ordenar=abertura_desc" \
  --data-urlencode "por_pagina=50"

Ficha de empresa

GET https://evodata.app/api/v1/empresas/{cnpj}

Retorna um único estabelecimento com todo o detalhamento. O CNPJ pode vir com ou sem máscara e é validado pelos dígitos verificadores antes de qualquer consulta — um CNPJ malformado devolve 422 sem tocar o banco.

curl "https://evodata.app/api/v1/empresas/62.170.939/0001-51"
curl "https://evodata.app/api/v1/empresas/62170939000151"   # equivalente

A resposta é { "dados": { … } } com todos os campos do objeto Empresa, mais os seguintes:

Objeto sócio

{
  "nome": "FULANO DE TAL",
  "documento": "***040852**",        # PF sempre parcial
  "tipo": "Pessoa física",
  "eh_pessoa_juridica": false,
  "qualificacao": "Sócio-Administrador",
  "entrada": "2019-03-12",
  "faixa_etaria": "41 a 50 anos",
  "representante": null
}

Objeto simples

{
  "optante": true,
  "desde": "2020-01-01",
  "excluido_em": null,
  "mei": true,
  "mei_desde": "2020-01-01",
  "mei_excluido_em": null
}

Objeto unidade

Lista com todas as unidades que compartilham a mesma raiz de CNPJ, incluindo a própria consultada. Útil para navegar de uma filial à matriz.

{
  "cnpj": "62170939000151",
  "cnpj_formatado": "62.170.939/0001-51",
  "nome_fantasia": null,
  "tipo": "Matriz",
  "eh_matriz": true,
  "situacao": "Ativa",
  "ativa": true,
  "uf": "DF",
  "municipio": "BRASILIA",
  "cnae": "Cabeleireiros, manicure e pedicure",
  "abertura": "2025-08-11"
}

Buscar pessoas

GET https://evodata.app/api/v1/pessoas chave + plano pago

Busca sobre 233 milhões de pessoas físicas. Ao menos um filtro é obrigatório. Diferente da busca de empresas, aqui não há paginação: o parâmetro por_pagina define quantas linhas voltam, e tem_mais indica se existem outras. Percorrer profundamente um conjunto de centenas de milhões de linhas não é uma operação que esta base sustente — o caminho é refinar até o recorte caber.

Parâmetros

Resposta

{
  "dados": [
    {
      "id": 2091705,
      "nome": "MARIA APARECIDA SILVA",
      "cpf": "***.456.789-**",
      "nome_mae": "ROSA MARIA BELLONI",
      "sexo": "F",
      "sexo_descricao": "Feminino",
      "nascimento": "1975-03-22",
      "idade": 51,
      "estado_civil": "C",
      "estado_civil_descricao": "Casado(a)",
      "cbo": "2521",
      "cidade": "SAO PAULO",
      "uf": "SP",
      "ddd": 11,
      "telefone": 999998888
    }
  ],
  "paginacao": {
    "por_pagina": 25,
    "retornados": 25,
    "tem_mais": true,
    "amostra": false
  },
  "consulta": {
    "condutor": "pessoas",
    "ms": 32
  }
}

O bloco consulta é diagnóstico: condutor revela por qual tabela a consulta entrou, o que explica por que uma combinação ficou lenta. Filtros exatos — CPF, telefone, e-mail, CEP, PIS — conduzem por índice único e respondem em milissegundos; uf ou sexo sozinhos conduzem mal e tendem a virar amostra ou 503.

Exemplo

curl -H "Authorization: Bearer evd_SUA_CHAVE" -G "https://evodata.app/api/v1/pessoas" \
  --data-urlencode "nome=MARIA" \
  --data-urlencode "nome_mae=ANA" \
  --data-urlencode "uf=SP" \
  --data-urlencode "por_pagina=50"

Ficha de pessoa

GET https://evodata.app/api/v1/pessoas/{id} chave + plano pago

O id é o identificador interno devolvido no campo id da busca — não é o CPF, que nunca sai em claro por nenhum endpoint.

A resposta traz todos os campos da linha de busca, mais os blocos:

Tabelas de referência

Os filtros cnae e municipio esperam códigos. Estes dois endpoints resolvem nome para código e servem bem a campos de autocompletar.

Buscar CNAE

GET https://evodata.app/api/v1/referencias/cnae?q={termo}

Busca textual na descrição das atividades. Termos com menos de 2 caracteres devolvem lista vazia e 200 — não é erro.

curl "https://evodata.app/api/v1/referencias/cnae?q=padaria"

{
  "dados": [
    { "codigo": 1091102, "descricao": "Fabricação de produtos de padaria e confeitaria com predominância de produção própria" },
    { "codigo": 4721101, "descricao": "Padaria e confeitaria com predominância de produção própria" },
    { "codigo": 4721102, "descricao": "Padaria e confeitaria com predominância de revenda" }
  ]
}

Municípios por UF

GET https://evodata.app/api/v1/referencias/municipios/{uf}

Todos os municípios de um estado, com o código que o filtro municipio espera. A sigla não diferencia maiúsculas.

curl "https://evodata.app/api/v1/referencias/municipios/df"

{ "dados": [ { "codigo": "9701", "nome": "BRASILIA" } ] }

Erros

Respostas de erro trazem erro, um código estável seguro para comparar em código, e quase sempre mensagem, texto em português voltado a quem lê — sujeito a mudar de redação. Compare pelo erro, nunca pela mensagem.

{
  "erro": "filtros_ausentes",
  "mensagem": "Informe ao menos um filtro. A base tem 72 milhões de estabelecimentos e uma consulta irrestrita não é atendida."
}

O 503 consulta_expirada merece tratamento próprio: ele não indica indisponibilidade, e sim que aquela combinação de filtros é ampla demais para o tempo limite do banco. Repetir a mesma chamada tende a falhar de novo — o caminho é acrescentar um recorte mais estreito, como UF ou município. Vale notar que a consulta expirada não fica em cache: se o cache do PostgreSQL esquentar por outra via, a mesma chamada pode passar depois.

Enumerações

uf

AC AL AP AM BA CE DF ES GO MA MT MS MG PA PB PR PE PI RJ RN RS RO RR SC SP SE TO EX

EX designa estabelecimento sediado no exterior.

Limitações conhecidas

Nem tudo que a interface web faz está exposto por HTTP. Vale conhecer as fronteiras antes de desenhar a integração.

• O CPF nunca sai em claro. Nenhum endpoint devolve o número completo — busca, ficha e vínculos trazem sempre a forma mascarada ***.XXX.XXX-**. A busca por CPF exige os 11 dígitos, de modo que a API confirme uma identidade que você já tem, em vez de permitir descobri-las.
• Não há exportação em massa. O teto é 100 itens por página, e a paginação profunda fica cara porque o banco precisa descartar tudo que veio antes. Para volumes grandes, use a exportação da interface, que percorre o conjunto por chave e não repete nem omite registros.
• Não há ordenação garantida. Qualquer valor de ordenar pode ser recusado em conjuntos grandes — a resposta continua 200, com a explicação em avisos. Um cliente que dependa de ordem precisa checar esse array.
• Não há webhooks nem notificação de mudança. A base acompanha as publicações mensais da Receita Federal; descobrir o que mudou exige reconsultar.
• Respostas são cacheadas. Buscas e fichas passam por cache de curta duração. Duas chamadas idênticas em sequência podem devolver exatamente o mesmo corpo mesmo que a base tenha mudado no meio.