Skip to content

Data Stone API (1.0)

A API da Data Stone fornece acesso a dados enriquecidos de pessoas físicas e jurídicas do Brasil.

Funcionalidades principais:

  • Consulta de informações de pessoas e empresas
  • Prospecção e busca avançada com filtros personalizados
  • Enriquecimento de dados B2B em lote
  • Dados auxiliares (CNAE, CBO, geolocalização)
  • Validação de contatos WhatsApp

Base URL: https://api.datastone.com.br/v1

Autenticação

Todas as requisições requerem uma API Key no header Authorization.

Como obter sua API Key: Acesse seu perfil no painel e gere uma nova chave. Ao copiar, ela já virá no formato correto.

Formato obrigatório:

Authorization: Token <sua-api-key>

Exemplos de uso:

Python:

import requests

headers = {
    'Authorization': 'Token abc123suachaveaqui'
}

response = requests.get('https://api.datastone.com.br/v1/saldo', headers=headers)

JavaScript:

fetch('https://api.datastone.com.br/v1/saldo', {
    headers: {
        'Authorization': 'Token abc123suachaveaqui'
    }
})

cURL:

curl -H "Authorization: Token abc123suachaveaqui" https://api.datastone.com.br/v1/saldo

Webhooks

Sistema de notificação automática via POST ao final de processos de enriquecimento ou prospecção.

  • Cadastro: Via perfil do administrador com teste automático de disponibilidade da URL
  • Método: POST (enviado pela API para o cliente)
  • Retry Policy: 3 tentativas com intervalo de 1 minuto entre cada
  • Timeout: 30 segundos por requisição
  • Resposta requerida: HTTP 200 imediato

Payload do Webhook:

{
  "job_id": 123,
  "job_type": "enrichment",
  "status": "done"
}

Valores possíveis para job_type: enrichment, prospecting

Valores possíveis para status: requested, done, error

Rate Limiting

Limite Padrão: 100 requisições por dia (compartilhado entre API e painel)

  • Personalização: Limites podem ser customizados por conta/empresa
  • Whitelist de IPs: Administradores podem adicionar IPs que ficam isentos do rate limit
  • Resposta quando excedido: Status Code 429 Too Many Requests com bloqueio de 24 horas

Limite de Produto

Controle de uso por tipo de produto (gerenciado por administradores):

  • B2C (Consulta, Enriquecimento, Prospecção): 100.000 requisições/mês
  • B2B (Prospecção B2B, Consulta B2B): 50.000 requisições/mês

Resposta quando excedido: Status Code 429 Too Many Requests até início do próximo período

Erros Comuns e Como Resolver

Erro 401 - API Key Inválida

{
  "detail": "Verifique o token informado."
}

Causa: A API Key está incorreta ou o formato do header está errado.

Solução:

  1. Verifique se copiou a API Key corretamente (sem espaços extras no início ou fim)
  2. Confirme que o header está exatamente assim: Authorization: Token sua-api-key
  3. Se necessário, gere uma nova API Key no painel

Erro 401 - IP Não Autorizado

{
  "detail": "Acesso não autorizado. O IP 192.168.1.1 não está na lista de IPs permitidos. Adicione este IP na whitelist da sua empresa para liberar o acesso."
}

Causa: Seu IP não está cadastrado na whitelist da empresa.

Solução:

  1. Copie o IP que aparece na mensagem de erro
  2. Acesse o painel da Data Stone
  3. Vá em Meu Perfil > Whitelist de IPs
  4. Adicione o IP copiado
  5. Aguarde alguns segundos e tente novamente

Erro 400 - Saldo Insuficiente

{
  "error": {
    "code": "no credits",
    "description": "Você não possui saldo suficiente, disponível 0"
  }
}

Causa: Sua conta não tem créditos suficientes para a operação.

Solução: Adquira mais créditos no painel ou entre em contato com o suporte.


Erro 429 - Limite de Requisições Excedido

{
  "detail": "O limite de utilização por usuário foi excedido. Contate o seu administrador para aumentar ou aguarde o reinício do ciclo no próximo mês."
}

Causa: Você excedeu o limite de requisições diárias ou mensais.

Solução:

  • Aguarde até o próximo mês para o ciclo reiniciar
  • Solicite aumento de limite com o administrador da sua empresa
  • Adicione seu IP na whitelist para ficar isento do rate limit diário

Automação com n8n — Zero Código

n8n

Use toda a API da Data Stone sem escrever uma linha de código.

Temos um nó comunitário oficial para o n8n — a plataforma open-source de automação com mais de 400 integrações. Arraste, conecte, execute. É isso.


Por que usar?

  • Sem código: Monte workflows visuais arrastando blocos — prospecção, enriquecimento, consulta, tudo na interface
  • Integração total: Conecte a Data Stone a CRMs (HubSpot, Pipedrive), planilhas (Google Sheets), email (Gmail, SendGrid), Slack, Telegram e centenas de outros serviços
  • Templates prontos: Importe workflows completos com um clique e comece a usar em minutos
  • Exportação CSV: Todos os templates já geram arquivos CSV prontos para download ou envio automático
  • Agende execuções: Rode prospecções periódicas, monitore mudanças em dados de empresas e contatos automaticamente

Instalação rápida

  1. No n8n, acesse Settings > Community Nodes
  2. Clique em Install a community node
  3. Digite n8n-nodes-datastone
  4. Clique em Install
  5. Crie uma credencial Data Stone API e cole sua API Key
  6. Pronto — todos os recursos ficam disponíveis nos seus workflows

O que está coberto

O nó oferece acesso completo à API:

RecursoOperações
PessoaConsultar por CPF, Buscar, Busca Avançada
EmpresaConsultar por CNPJ, Buscar, Buscar Filiais
B2B PessoaProspectar, Enriquecer, Enriquecer em Lote
B2B EmpresaProspectar, Enriquecer, Enriquecer em Lote
EnriquecimentoListar Layouts, Criar, Consultar Status
ContaConsultar Saldo

Templates prontos para importar

Copie a URL, cole no n8n em "..." > "Import from URL..." e o workflow aparece pronto para configurar:

TemplateURL
Prospecção B2B - Pessoashttps://raw.githubusercontent.com/Data-Stone/n8n-nodes-datastone/main/n8n_examples/01_prospeccao_b2b_pessoas.json
Prospecção B2B - Empresashttps://raw.githubusercontent.com/Data-Stone/n8n-nodes-datastone/main/n8n_examples/02_prospeccao_b2b_empresas.json
Consulta Pessoa por CPFhttps://raw.githubusercontent.com/Data-Stone/n8n-nodes-datastone/main/n8n_examples/03_consulta_pessoa_cpf.json
Busca de Pessoahttps://raw.githubusercontent.com/Data-Stone/n8n-nodes-datastone/main/n8n_examples/04_busca_pessoa.json
Consulta Empresa por CNPJhttps://raw.githubusercontent.com/Data-Stone/n8n-nodes-datastone/main/n8n_examples/05_consulta_empresa_cnpj.json
Busca de Empresahttps://raw.githubusercontent.com/Data-Stone/n8n-nodes-datastone/main/n8n_examples/06_busca_empresa.json

Use como base para suas automações

Os templates foram feitos para servir como ponto de partida. Importe, ajuste os filtros e conecte aos serviços que você já usa. Algumas ideias:

  • Prospecção + CRM: Encontre contatos B2B e crie leads automaticamente no HubSpot, Pipedrive ou Salesforce
  • Enriquecimento + Email: Enriqueça contatos e dispare sequências de email via Mailchimp, SendGrid ou Gmail
  • Consulta + Google Sheets: Consulte CPFs/CNPJs em lote a partir de uma planilha e grave os resultados de volta
  • Monitoramento automático: Agende execuções periódicas para acompanhar mudanças nos dados de empresas e contatos
  • Qualificação de leads: Combine consulta de pessoa + empresa para validar e pontuar leads antes de entrar no funil de vendas
  • Notificações: Envie alertas via Slack, Telegram ou WhatsApp quando novos contatos forem encontrados na prospecção

O n8n tem mais de 400 integrações nativas. Combine a Data Stone com qualquer uma delas e monte o fluxo ideal para o seu negócio.

Download OpenAPI description
Languages
Servers
Mock server
https://docs.datastone.com.br/_mock/api
Servidor de Produção
https://api.datastone.com.br/v1

Operações de consulta direta para pessoas físicas (CPF), empresas (CNPJ), validação de WhatsApp e verificação de saldo.

Operations

Operações de prospecção e enriquecimento B2B para pessoas e empresas, incluindo filtros avançados, busca com autocomplete e enriquecimento em lote.

Operations

Request

Retorna documentação completa sobre filtros disponíveis para buscas de Pessoas e Empresas. Inclui nomes de campos, tipos de dados, descrições e indicadores de obrigatoriedade.

Security
ApiKeyAuth
curl -i -X GET \
  https://docs.datastone.com.br/_mock/api/b2b/filter-structure/ \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Estrutura de filtros retornada com sucesso

Bodyapplication/json
object

Documentação de filtros disponíveis

Response
application/json
{}

Request

Retorna todas as opções pré-definidas para filtros categóricos da API B2B.

REGRA IMPORTANTE: Para filtros com texto e valor, SEMPRE enviar o valor.

  • ✅ Válido: {"estado": "SP"}
  • ❌ Inválido: {"estado": "São Paulo"}
Security
ApiKeyAuth
curl -i -X GET \
  https://docs.datastone.com.br/_mock/api/b2b/filter-options/ \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Opções de filtros retornadas com sucesso

Bodyapplication/json
object

Opções disponíveis para cada filtro categórico

Response
application/json
{}

Request

Prospecção B2B de pessoas físicas com filtros avançados de perfil profissional e empresa.

Modelo de cobrança:

  • Primeira requisição (sem chave de cache): 1 crédito B2B
  • Paginação (com chave de cache): 0 créditos
  • Expiração do cache: 7 dias

O campo id_pessoa retornado pode ser usado no endpoint de Enriquecimento de Pessoas.

Security
ApiKeyAuth
Bodyapplication/jsonrequired
paginainteger>= 1

Número da página

Example: 1
por_paginainteger[ 1 .. 50 ]

Itens por página (máximo 50)

Example: 20
chave_cachestring

Chave de cache (economiza créditos em requisições subsequentes)

Example: "abc123xyz"
filtros_pessoaobject(FiltrosPessoa)
filtros_empresaobject(FiltrosEmpresa)
url_webhookstring

URL para callback assíncrono

Example: "https://seusite.com/webhook"
curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/b2b/persons/ \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "pagina": 1,
    "por_pagina": 20,
    "chave_cache": "abc123xyz",
    "filtros_pessoa": {
      "departamentos": [
        "Tecnologia",
        "Marketing"
      ],
      "niveis_senioridade": [
        "Sênior",
        "Pleno"
      ],
      "cargos": [
        "Desenvolvedor",
        "Gerente"
      ],
      "habilidades": [
        "Python",
        "JavaScript"
      ],
      "periodos_trabalho": [
        {}
      ],
      "localizacoes": [
        "São Paulo, SP"
      ],
      "estados": [
        "SP",
        "RJ"
      ],
      "has_email": true,
      "has_phone": true,
      "has_cnpj": true,
      "has_linkedin": true
    },
    "filtros_empresa": {
      "nome_empresa": [
        "Google Brasil Internet Ltda"
      ],
      "localizacoes": [
        "São Paulo, SP",
        "Rio de Janeiro, RJ"
      ],
      "estados": [
        "SP",
        "RJ"
      ],
      "setores": [
        "Tecnologia",
        "Educação"
      ],
      "atividades_cnae": [
        "6201500"
      ],
      "especialidades": [
        "Software"
      ],
      "tamanhos_empresa": [
        "11-50",
        "51-200"
      ],
      "naturezas_juridicas": [
        1,
        2,
        3
      ],
      "tipos_trabalho": [
        "Empresa Privada"
      ],
      "data_fundacao": {
        "data_inicio": "2010-01-01",
        "data_fim": "2023-12-31"
      },
      "faixa_receita": {
        "receita_minima": 100000,
        "receita_maxima": 5000000
      },
      "incluir_mei": true,
      "tem_cnpj": true,
      "tem_email": true,
      "tem_telefone": true,
      "tem_linkedin": true
    },
    "url_webhook": "https://seusite.com/webhook"
  }'

Responses

Pessoas encontradas com sucesso

Bodyapplication/json
chave_cachestring

Chave para usar em paginação (evita custos adicionais)

Example: "abc123xyz"
totalinteger

Total de resultados encontrados

Example: 150
resultadosArray of objects
Response
application/json
{ "chave_cache": "abc123xyz", "total": 150, "resultados": [ {} ] }

Request

Enriquece perfil de pessoa física individualmente com processamento assíncrono.

Custo: 1 crédito por registro enriquecido com sucesso

Dados retornados:

  • Básicos: nome completo, CPF (quando disponível), idade, gênero, localização
  • Contatos: telefones, emails, perfis públicos
  • Vínculos empresariais: participações, cargos corporativos, CNPJs
  • Histórico profissional: cargos, empresas, períodos
  • Educação: cursos, instituições, níveis de escolaridade

A notificação de conclusão é enviada via webhook (se configurado).

Security
ApiKeyAuth
Bodyapplication/jsonrequired
contatoobject
url_webhookstring

URL para notificação de conclusão

Example: "https://seusite.com/webhook"
curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/b2b/persons/enrich \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "contato": {
      "url_linkedin": "https://www.linkedin.com/in/exemplo",
      "email": "exemplo@empresa.com",
      "id_pessoa": 12345
    },
    "url_webhook": "https://seusite.com/webhook"
  }'

Responses

Enriquecimento concluído com sucesso

Bodyapplication/json
id_processamentostring

ID único do processamento

Example: "4cb319e3bd9544019b45fd56911fa160"
statusstring
Enum"completed""processing""failed"
Example: "completed"
totalinteger

Total de contatos processados

Example: 1
sucessointeger

Quantidade de enriquecimentos bem-sucedidos

Example: 1
falhouinteger

Quantidade de enriquecimentos que falharam

Example: 0
contatosArray of objects
timestampnumber(float)
Example: 1760542724.0121257
Response
application/json
{ "id_processamento": "4cb319e3bd9544019b45fd56911fa160", "status": "completed", "total": 1, "sucesso": 1, "falhou": 0, "contatos": [ {} ], "timestamp": 1760542724.0121257 }

Request

Enriquecimento em massa de pessoas físicas com processamento assíncrono e entrega via webhook.

Custo: 1 crédito por registro enriquecido com sucesso

Dados retornados: Mesmos do enriquecimento individual

Security
ApiKeyAuth
Bodyapplication/jsonrequired
contatosArray of objectsrequired

Array de contatos para enriquecer

contatos[].​url_linkedinstring
Example: "https://www.linkedin.com/in/exemplo"
contatos[].​emailstring
Example: "exemplo@empresa.com"
contatos[].​id_pessoainteger
Example: 12345
url_webhookstring

URL para notificação de conclusão

Example: "https://seusite.com/webhook"
curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/b2b/persons/enrich/bulk \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "contatos": [
      {
        "url_linkedin": "https://www.linkedin.com/in/exemplo",
        "email": "exemplo@empresa.com",
        "id_pessoa": 12345
      }
    ],
    "url_webhook": "https://seusite.com/webhook"
  }'

Responses

Job de enriquecimento em lote criado com sucesso

Bodyapplication/json
job_idinteger
Example: 12345
statusstring
Example: "requested"
total_contactsinteger
Example: 100
Response
application/json
{ "job_id": 12345, "status": "requested", "total_contacts": 100 }

Request

Prospecção B2B de empresas usando dados públicos, registros oficiais e LinkedIn.

Modelo de cobrança:

  • Primeira requisição (sem chave de cache): 1 crédito B2B
  • Paginação (com chave de cache): 0 créditos
  • Expiração do cache: 7 dias

REGRA IMPORTANTE: Ao preencher localizacoes, deixe estados vazio, e vice-versa.

Security
ApiKeyAuth
Bodyapplication/jsonrequired
paginainteger>= 1
Example: 1
por_paginainteger[ 1 .. 50 ]
Example: 20
chave_cachestring

Chave de cache (economiza créditos)

Example: "abc123xyz"
filtros_empresaobject(FiltrosEmpresa)
curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/b2b/companies/ \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "pagina": 1,
    "por_pagina": 20,
    "chave_cache": "abc123xyz",
    "filtros_empresa": {
      "nome_empresa": [
        "Google Brasil Internet Ltda"
      ],
      "localizacoes": [
        "São Paulo, SP",
        "Rio de Janeiro, RJ"
      ],
      "estados": [
        "SP",
        "RJ"
      ],
      "setores": [
        "Tecnologia",
        "Educação"
      ],
      "atividades_cnae": [
        "6201500"
      ],
      "especialidades": [
        "Software"
      ],
      "tamanhos_empresa": [
        "11-50",
        "51-200"
      ],
      "naturezas_juridicas": [
        1,
        2,
        3
      ],
      "tipos_trabalho": [
        "Empresa Privada"
      ],
      "data_fundacao": {
        "data_inicio": "2010-01-01",
        "data_fim": "2023-12-31"
      },
      "faixa_receita": {
        "receita_minima": 100000,
        "receita_maxima": 5000000
      },
      "incluir_mei": true,
      "tem_cnpj": true,
      "tem_email": true,
      "tem_telefone": true,
      "tem_linkedin": true
    }
  }'

Responses

Empresas encontradas com sucesso

Bodyapplication/json
chave_cachestring
Example: "abc123xyz"
totalinteger
Example: 250
resultadosArray of objects
Response
application/json
{ "chave_cache": "abc123xyz", "total": 250, "resultados": [ {} ] }

Request

Enriquece perfil de empresa individualmente com processamento assíncrono.

Custo: 1 crédito por registro enriquecido

Dados retornados:

  • Cadastro: razão social, nome fantasia, data de fundação, CNAEs
  • Localização: endereço completo, cidade, estado, CEP, geolocalização
  • Contatos: telefones, emails, website oficial
  • Informações: setor, descrição, número de funcionários, links públicos
  • Estrutura corporativa: sócios, administradores, percentuais de participação
  • Histórico: ex-sócios e ex-funcionários
  • Filiais e equipe atual
Security
ApiKeyAuth
Bodyapplication/jsonrequired
contatoobject
url_webhookstring

URL para notificação de conclusão

Example: "https://seusite.com/webhook"
curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/b2b/companies/enrich \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "contato": {
      "url_linkedin": "https://www.linkedin.com/company/exemplo",
      "cnpj": "12345678000199",
      "id_empresa": 98765
    },
    "url_webhook": "https://seusite.com/webhook"
  }'

Responses

Enriquecimento concluído com sucesso

Bodyapplication/json
id_processamentostring

ID único do processamento

Example: "00000000000000000000000000000000"
statusstring
Enum"completed""processing""failed"
Example: "completed"
totalinteger

Total de contatos processados

Example: 1
sucessointeger

Quantidade de enriquecimentos bem-sucedidos

Example: 1
falhouinteger

Quantidade de enriquecimentos que falharam

Example: 0
contatosArray of objects
timestampnumber(float)
Example: 1760632949
Response
application/json
{ "id_processamento": "00000000000000000000000000000000", "status": "completed", "total": 1, "sucesso": 1, "falhou": 0, "contatos": [ {} ], "timestamp": 1760632949 }

Request

Enriquecimento em massa de empresas com processamento assíncrono.

Custo: 1 crédito por registro enriquecido

Dados retornados: Mesmos do enriquecimento individual

Security
ApiKeyAuth
Bodyapplication/jsonrequired
contatosArray of objectsrequired

Array de empresas para enriquecer

contatos[].​url_linkedinstring
Example: "https://www.linkedin.com/company/exemplo"
contatos[].​cnpjstring
Example: "12345678000199"
contatos[].​id_empresainteger
Example: 98765
url_webhookstring

URL para notificação de conclusão

Example: "https://seusite.com/webhook"
curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/b2b/companies/enrich/bulk \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "contatos": [
      {
        "url_linkedin": "https://www.linkedin.com/company/exemplo",
        "cnpj": "12345678000199",
        "id_empresa": 98765
      }
    ],
    "url_webhook": "https://seusite.com/webhook"
  }'

Responses

Job de enriquecimento em lote criado com sucesso

Bodyapplication/json
job_idinteger
Example: 12345
statusstring
Example: "requested"
total_companiesinteger
Example: 50
Response
application/json
{ "job_id": 12345, "status": "requested", "total_companies": 50 }

Operações de enriquecimento de dados em lote com layouts personalizáveis e processamento assíncrono.

Operations

Operações de prospecção com filtros geográficos e profissionais, incluindo contagem e geração de jobs de prospecção.

Operations

Dados auxiliares como CNAE, CBO, geolocalização (estados, cidades, bairros) e setores empresariais.

Operations