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

Caso de uso: montar uma planilha de leads B2B

O fluxo completo — de um filtro a uma lista de pessoas com e-mail e telefone, junto com os dados da empresa de cada uma. São dois pares de chamadas: buscar (barato, cacheado) e enriquecer (é onde o crédito é consumido de fato).

1. Buscar as pessoas

curl -X POST https://api.datastone.com.br/v1/b2b/persons/ \
  -H "Authorization: Token $DATASTONE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pagina": 1,
    "por_pagina": 50,
    "filtros_empresa": {"tamanhos_empresa": ["1001-5000", "201-500", "501-1000"]},
    "filtros_pessoa": {"niveis_senioridade": ["Decisores", "Sênior"]}
  }'

A resposta traz nome, cargo, id_pessoa e id_empresa, mais o total e a chave_cache:

{
  "dados": [{"id_pessoa": 12345, "nome": "...", "cargo": "...", "id_empresa": 678}],
  "total": 94660,
  "pagina": 1,
  "por_pagina": 50,
  "chave_cache": "124559",
  "sucesso": true
}

Guarde a chave_cache. Para as páginas seguintes, reenvie-a junto com total_cacheado — assim a busca não é refeita e as demais páginas não custam nada:

{
  "pagina": 2,
  "por_pagina": 50,
  "filtros_empresa": {"tamanhos_empresa": ["1001-5000", "201-500", "501-1000"]},
  "chave_cache": "124559",
  "total_cacheado": 94660
}

2. Enriquecer as pessoas

Envie os id_pessoa da etapa anterior. Esta chamada cobra 1 crédito por registro — é o custo real do fluxo.

curl -X POST https://api.datastone.com.br/v1/b2b/persons/enrich/bulk \
  -H "Authorization: Token $DATASTONE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contatos": [{"id_pessoa": 12345}, {"id_pessoa": 67890}],
    "url_webhook": "https://seu-sistema.com/webhook/b2b"
  }'

A resposta é imediata e não traz os dados — o processamento é assíncrono:

{
  "sucesso": true,
  "id_processamento": "12235a8ea7b04bde8d49737359339fd2",
  "quantidade": 2,
  "url_webhook": "https://seu-sistema.com/webhook/b2b"
}

3. Obter o resultado

Com url_webhook, o resultado chega sozinho quando terminar. Sem webhook, consulte o status — ele devolve os mesmos dados:

curl https://api.datastone.com.br/v1/b2b/status/12235a8ea7b04bde8d49737359339fd2 \
  -H "Authorization: Token $DATASTONE_TOKEN"

Valores possíveis para status:

Status	Significado	Traz `contatos`?
`processing`	Ainda executando. Acompanhe por `completados` / `total_registros`.	Não
`completed`	Terminou. Confira `sucesso` e `falhou`.	Sim
`failed`	Falhou no lote inteiro (crédito insuficiente ou exceção). O motivo vem em `erro`.	Sim, quando houver

Como fazer o polling: repita a chamada a cada ~10 segundos enquanto status for processing, e pare no primeiro completed ou failed. A resposta concluída fica em cache por 30 segundos, então consultar com frequência maior não antecipa o resultado. Consultar o status é gratuito — não debita crédito.

import time, requests
url = f"https://api.datastone.com.br/v1/b2b/status/{id_processamento}" cabecalho = {"Authorization": f"Token {token}"}
while True:
    resultado = requests.get(url, headers=cabecalho, timeout=60).json()
    if resultado["status"] != "processing":
        break
    time.sleep(10)

if resultado["status"] == "failed":
    raise RuntimeError(resultado.get("erro", "processamento falhou"))

for contato in resultado["contatos"]:
    print(contato["status"], contato.get("detalhes_contato"))

4. Completar com os dados da empresa

Repita os passos 1 e 2 no lado das empresas — POST /b2b/companies/ e POST /b2b/companies/enrich/bulk — e junte os dois lados pelo id_empresa. É assim que se obtêm razão social, faixa de faturamento, site e os contatos corporativos.

Como o crédito é consumido

Esta é a parte que mais gera dúvida:

A busca cobra por combinação nova de filtros, não por chamada. Repetir a mesma busca não cobra de novo enquanto a chave de cache valer. Um agendador que roda de hora em hora com o mesmo filtro faz 24 chamadas por dia e consome pouquíssimo crédito.
Ordene as listas de filtro e mantenha a ordem estável entre execuções. ["a","b"] e ["b","a"] descrevem o mesmo conjunto, mas se o seu código gerar a ordem de forma variável, cada variação pode ser tratada como uma busca nova.
Paginar com chave_cache é gratuito. Sem ela, cada página vira uma busca nova.
O enriquecimento cobra 1 crédito por registro e é o custo dominante. Guarde os id_pessoa e id_empresa já enriquecidos e não os reenvie.
Registros que falham são estornados automaticamente — o campo falhou do resultado indica quantos foram.
Consultar o status não custa nada.

Guia completo com exemplos executáveis

Este fluxo, com requisições e respostas reais, está detalhado em https://github.com/Data-Stone/api-exemplos — incluindo o enriquecimento de empresas por CNPJ, o polling do status, o tratamento de falha parcial em lote e o consumo de créditos.

Buscar uma empresa específica por CNPJ

A busca por filtros não aceita CNPJ. Para resolver um CNPJ conhecido, use o campo document — ele devolve o id_empresa, que serve de entrada para o enriquecimento:

curl -X POST https://api.datastone.com.br/v1/b2b/companies/ \
  -H "Authorization: Token $DATASTONE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"document": "14568725000195"}'

{"success": true, "data": {"company_id": 44235793}}

Aceita CNPJ com ou sem formatação. Responde 404 quando não há empresa para o documento informado. O campo url_linkedin funciona da mesma forma, a partir da URL do perfil da empresa.

Créditos e carência de cobrança

Nem toda requisição debita crédito. Duas regras evitam pagar duas vezes pelo mesmo dado — e a segunda consulta devolve a resposta completa do mesmo jeito, sem nenhuma indicação de que foi isenta.

Consulta por documento (/persons/, /companies/) — 24 horas. O mesmo CPF ou CNPJ consultado de novo pela sua empresa dentro de 24 horas não gera novo débito. A carência é por documento e por conta: chaves de API diferentes da mesma empresa compartilham a janela. Consulta sem retorno não cobra nem inicia a carência.

Prospecção B2B (/b2b/persons/, /b2b/companies/) — 7 dias. A mesma busca, com os mesmos filtros, não é cobrada de novo dentro de 7 dias. Reenviar a chave_cache devolvida na primeira requisição é a forma recomendada de paginar sem gasto adicional (0 créditos em vez de 1). Mudança de página (offSet/fetchNext) não caracteriza busca nova.

Consultas que não entram em nenhuma carência: buscas por nome, telefone ou e-mail (/persons/search/, /company/list/), validação de WhatsApp e enriquecimento em lote — cada requisição com retorno é cobrada.

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:

Verifique se copiou a API Key corretamente (sem espaços extras no início ou fim)
Confirme que o header está exatamente assim: Authorization: Token sua-api-key
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:

Copie o IP que aparece na mensagem de erro
Acesse o painel da Data Stone
Vá em Meu Perfil > Whitelist de IPs
Adicione o IP copiado
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

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.

github.com/Data-Stone/n8n-nodes-datastone

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

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

O que está coberto

O nó oferece acesso completo à API:

Recurso	Operações
Pessoa	Consultar por CPF, Buscar, Busca Avançada
Empresa	Consultar por CNPJ, Buscar, Buscar Filiais
B2B Pessoa	Prospectar, Enriquecer, Enriquecer em Lote
B2B Empresa	Prospectar, Enriquecer, Enriquecer em Lote
Enriquecimento	Listar Layouts, Criar, Consultar Status
Conta	Consultar Saldo

Templates prontos para importar

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

Template	URL
Prospecção B2B - Pessoas	`https://raw.githubusercontent.com/Data-Stone/n8n-nodes-datastone/main/n8n_examples/01_prospeccao_b2b_pessoas.json`
Prospecção B2B - Empresas	`https://raw.githubusercontent.com/Data-Stone/n8n-nodes-datastone/main/n8n_examples/02_prospeccao_b2b_empresas.json`
Consulta Pessoa por CPF	`https://raw.githubusercontent.com/Data-Stone/n8n-nodes-datastone/main/n8n_examples/03_consulta_pessoa_cpf.json`
Busca de Pessoa	`https://raw.githubusercontent.com/Data-Stone/n8n-nodes-datastone/main/n8n_examples/04_busca_pessoa.json`
Consulta Empresa por CNPJ	`https://raw.githubusercontent.com/Data-Stone/n8n-nodes-datastone/main/n8n_examples/05_consulta_empresa_cnpj.json`
Busca de Empresa	`https://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.

Ver todos os templates e instruções detalhadas

Download OpenAPI description

api.json

api.yaml

Languages

Servers

Mock server

https://docs.datastone.com.br/_mock/api

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