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.

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

  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.

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
Servidor de Produção
https://api.datastone.com.br/v1

Consulta

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

Operations

Prospecção B2B

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

Operations

Enriquecimento

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

Operations

Listar layouts de enriquecimento

Request

Retorna lista de layouts disponíveis para o processo de enriquecimento. Permite visualizar opções de formatação ao criar requisições.

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

Responses

Layouts retornados com sucesso

Bodyapplication/jsonArray [
idinteger
Example: 3
namestring
Example: "Standard - Email PF"
descriptionstring
Example: "Layout padrão com emails de pessoa física"
requires_parametersboolean
Example: true
]
Response
application/json
[
  {
    "id": 3,
    "name": "Standard - Email PF",
    "description": "Layout padrão com emails de pessoa física",
    "requires_parameters": true
  }
]

Solicitar enriquecimento

Request

Cria uma requisição de enriquecimento de dados com layout específico.

Campo parameters: Alguns layouts exigem configuração adicional.

Exemplo - Layout 3 (Standard - Email PF):

  • Define quantos emails por pessoa serão retornados
  • Limite máximo: 5 emails por pessoa
  • Formato: Array JSON, ex: ["2"] para 2 emails

Múltiplos Parâmetros: Devem ser enviados como array ordenado, ex: ["1", "1"]

Security
ApiKeyAuth
Bodyapplication/jsonrequired
namestring

Nome identificador do job de enriquecimento

Example: "Enriquecimento Base Clientes Janeiro"
layout_idintegerrequired

ID do layout a ser utilizado

Example: 3
parametersArray of strings

Parâmetros adicionais exigidos pelo layout

Example: ["2"]
filestring(byte)required

Arquivo em base64 contendo CPF/CNPJ para enriquecer

Example: "UEsDBBQABgAIAAAAIQ..."
callback_emailstring(email)

Email para notificação quando processamento concluir

Example: "usuario@empresa.com"
curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/enrichment/ \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Enriquecimento Base Clientes Janeiro",
    "layout_id": 3,
    "parameters": [
      "2"
    ],
    "file": "UEsDBBQABgAIAAAAIQ...",
    "callback_email": "usuario@empresa.com"
  }'

Responses

Enriquecimento solicitado com sucesso

Bodyapplication/json
idinteger

ID da requisição de enriquecimento

Example: 98765
statusstring
Example: "requested"
Response
application/json
{
  "id": 98765,
  "status": "requested"
}

Obter resultado do enriquecimento

Request

Recupera o resultado de uma requisição de enriquecimento.

Se webhook foi configurado, o status do processo será enviado automaticamente.

Security
ApiKeyAuth
Path
idintegerrequired

ID da requisição de enriquecimento

Example: 98765
curl -i -X GET \
  https://docs.datastone.com.br/_mock/api/enrichment/98765/result/ \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Resultado retornado com sucesso

Bodyapplication/json
filestring

URL temporária para download do arquivo CSV com os resultados do enriquecimento

Example: "https://storage.datastone.com.br/enrichment/results/98765-resultado.csv?token=abc123&expires=1769448958"
metricsobject

Estatísticas do enriquecimento processado

Response
application/json
{
  "file": "https://storage.datastone.com.br/enrichment/results/98765-resultado.csv?token=abc123&expires=1769448958",
  "metrics": {
    "Documentos enviados": 2,
    "Linhas enviadas": 2,
    "Telefone Fixo": 0,
    "Telefone Celular": 1,
    "E-mail": 3,
    "Documentos enriquecidos": 1,
    "Whatsapp ativo": 1
  }
}

Prospecção

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

Operations

Auxiliares

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

Operations