Data Stone API (1.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

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:

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

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

Prospecção

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

Operations

Prospecção de pessoas (contagem e job)

Request

Duas funcionalidades em um endpoint:

1. Modo Contagem (export: false)

Retorna quantidade total de pessoas que correspondem aos filtros
Não consome créditos

2. Modo Prospecção (export: true)

Cria job de prospecção com filtros especificados
Retorna job ID

Security

ApiKeyAuth

Bodyapplication/jsonrequired

exportbooleanrequired

false = contagem apenas, true = iniciar prospecção

Example: false

namestring

Nome da pessoa (aceita busca parcial)

Example: "MARIA"

citiesArray of strings

Cidades (formato "Cidade - UF")

Example: ["São Paulo - SP"]

statesArray of strings

Estados (sigla UF)

Example: ["SP"]

neighborhoodsArray of strings

Bairros

Example: ["Centro","Jardins"]

cbo_codesArray of strings

Códigos CBO de profissões

Example: ["252105","212305"]

genderstring

Gênero (M=Masculino, F=Feminino)

Enum"M""F"

Example: "M"

estimated_incomeArray of objects

Faixas de renda estimada

Example: [{"lower":"1000.00","upper":"500000.00"}]

birthdayobject

Período de data de nascimento

ageobject

Faixa etária

contact_channelsArray of strings

Canais de contato disponíveis

Items Enum"whatsapp""sms""phone""email""address"

Example: ["email","whatsapp"]

match_profileArray of strings

Códigos dos perfis predefinidos - usar campo "code" do endpoint /persons/prospect/profile

Example: ["PF1"]

quantityinteger>= 1

Quantidade de registros a exportar (apenas quando export=true)

Example: 1000

callback_emailstring(email)

Email para notificação quando job concluir (apenas quando export=true)

Example: "usuario@empresa.com"

planstring

Plano de extração (sempre "3" para export=true)

Value"3"

Example: "3"

file_formattingstring

Formato do arquivo de exportação (apenas quando export=true)

Enum"excel""csv"

Example: "excel"

curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/persons/prospect/ \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "export": false,
    "name": "MARIA",
    "cities": [
      "São Paulo - SP"
    ],
    "states": [
      "SP"
    ],
    "neighborhoods": [
      "Centro",
      "Jardins"
    ],
    "cbo_codes": [
      "252105",
      "212305"
    ],
    "gender": "M",
    "estimated_income": [
      {
        "lower": "1000.00",
        "upper": "500000.00"
      }
    ],
    "birthday": {
      "start_date": "1980-01-01",
      "end_date": "1990-12-31"
    },
    "age": {
      "lower": "18",
      "upper": "90"
    },
    "contact_channels": [
      "email",
      "whatsapp"
    ],
    "match_profile": [
      "PF1"
    ],
    "quantity": 1000,
    "callback_email": "usuario@empresa.com",
    "plan": "3",
    "file_formatting": "excel"
  }'

Responses

Resposta de contagem ou job criado

Bodyapplication/json

One of:

Resposta de contagem (export=false)

totalinteger

Example: 1500

Response

application/json

{
  "job_id": 12345,
  "status": "requested"
}

Prospecção de empresas (contagem e job)

Request

Duas funcionalidades em um endpoint:

1. Modo Contagem (export: false)

Retorna quantidade total de registros (empresas e sócios) que correspondem aos filtros
Não consome créditos

2. Modo Prospecção (export: true)

Inicia processo de coleta de informações detalhadas das empresas
Inclui dados de contato dos sócios
Retorna job ID

Security

ApiKeyAuth

Bodyapplication/jsonrequired

exportbooleanrequired

false = contagem apenas, true = iniciar prospecção

Example: false

namestring

Razão social ou nome fantasia (busca parcial)

Example: "TECNOLOGIA"

citiesArray of strings

Cidades (formato "Cidade - UF")

Example: ["Rio de Janeiro - RJ"]

statesArray of strings

Estados (sigla UF)

Example: ["RJ"]

cnae_codesArray of strings

Códigos CNAE

Example: ["5231101","6201500"]

headquarter_typestring

Tipo de sede: H=Matriz, B=Filial

Enum"H""B"

Example: "H"

estimated_employeesArray of objects

Array de faixas de número estimado de funcionários

Example: [{"upper":9},{"lower":10,"upper":49},{"lower":100},{"lower":"1","upper":"800"}]

estimated_createdArray of objects

Array de períodos de data de fundação

Example: [{"lower":"2023-11-18","upper":"2024-11-18"},{"upper":"2020-11-18"}]

revenuesArray of objects

Array de faixas de receita anual

Example: [{"lower":"10000.00","upper":"500000.00"}]

company_typeArray of strings

Porte da empresa

Items Enum"ME""EPP""DEMAIS"

Example: ["ME","EPP"]

nature_codesArray of strings

Códigos de natureza jurídica

Example: ["3999","1112","1104","1120"]

mei_typestring

Filtrar MEI

Enum"SIM""NAO"

Example: "NAO"

sector_codesArray of strings

Setores de atividade econômica

Example: ["ATIVIDADE FINANCEIRA SEGUROS","COMÉRCIO","INDUSTRIA"]

simple_typestring

Empresa optante pelo Simples Nacional

Enum"SIM""NAO"

Example: "SIM"

capitalsArray of objects

Array de faixas de capital social

Example: [{"lower":"5000.00","upper":"5000000.00"}]

import_exportstring

Tipo de operação de comércio exterior

Enum"IMPORTA""EXPORTA"

Example: "IMPORTA"

vehiclesArray of objects

Array de faixas de número de veículos

Example: [{"lower":"1","upper":"50"}]

quantityinteger>= 1

Quantidade de registros a exportar (apenas quando export=true)

Example: 500

callback_emailstring(email)

Email para notificação quando job concluir (apenas quando export=true)

Example: "usuario@empresa.com"

planstring

Plano de extração (sempre "3" para export=true)

Value"3"

Example: "3"

file_formattingstring

Formato do arquivo de exportação (apenas quando export=true)

Enum"excel""csv"

Example: "excel"

curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/company/prospect/ \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "export": false,
    "name": "TECNOLOGIA",
    "cities": [
      "Rio de Janeiro - RJ"
    ],
    "states": [
      "RJ"
    ],
    "cnae_codes": [
      "5231101",
      "6201500"
    ],
    "headquarter_type": "H",
    "estimated_employees": [
      {
        "upper": 9
      },
      {
        "lower": 10,
        "upper": 49
      },
      {
        "lower": 100
      },
      {
        "lower": "1",
        "upper": "800"
      }
    ],
    "estimated_created": [
      {
        "lower": "2023-11-18",
        "upper": "2024-11-18"
      },
      {
        "upper": "2020-11-18"
      }
    ],
    "revenues": [
      {
        "lower": "10000.00",
        "upper": "500000.00"
      }
    ],
    "company_type": [
      "ME",
      "EPP"
    ],
    "nature_codes": [
      "3999",
      "1112",
      "1104",
      "1120"
    ],
    "mei_type": "NAO",
    "sector_codes": [
      "ATIVIDADE FINANCEIRA SEGUROS",
      "COMÉRCIO",
      "INDUSTRIA"
    ],
    "simple_type": "SIM",
    "capitals": [
      {
        "lower": "5000.00",
        "upper": "5000000.00"
      }
    ],
    "import_export": "IMPORTA",
    "vehicles": [
      {
        "lower": "1",
        "upper": "50"
      }
    ],
    "quantity": 500,
    "callback_email": "usuario@empresa.com",
    "plan": "3",
    "file_formatting": "excel"
  }'

Responses

Resposta de contagem ou job criado

Bodyapplication/json

One of:

Resposta de contagem (export=false)

total_companiesinteger

Example: 850

total_partnersinteger

Example: 2100

Response

application/json

{
  "job_id": 54321,
  "status": "requested"
}

Obter resultado da prospecção

Request

Recupera o resultado de um job de prospecção.

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

Security

ApiKeyAuth

Path

job_idintegerrequired

ID do job de prospecção

Example: 12345

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

Responses

Resultado retornado com sucesso

Bodyapplication/json

job_idinteger

Example: 12345

statusstring

Enum"requested""done""error"

Example: "done"

resultobject

Dados prospectados

Response

application/json

{
  "job_id": 12345,
  "status": "done",
  "result": {}
}

Salvar filtro de prospecção

Request

Salva um conjunto de filtros para reutilização posterior.

Permite armazenar filtros complexos de pessoas ou empresas para uso recorrente.

Security

ApiKeyAuth

Bodyapplication/jsonrequired

filter_namestringrequired

Nome do filtro

Example: "Executivos SP"

filter_typeintegerrequired

Tipo de filtro (1=pessoas, 2=empresas)

Enum12

Example: 1

dataobjectrequired

Objeto contendo os filtros (mesma estrutura usada em /persons/prospect ou /company/prospect)

Example: {"cities":["São Paulo - SP"],"professions":["999999"],"age":{"min_age":30,"max_age":50}}

curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/prospection/filters/ \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter_name": "Executivos SP",
    "filter_type": 1,
    "data": {
      "cities": [
        "São Paulo - SP"
      ],
      "professions": [
        "999999"
      ],
      "age": {
        "min_age": 30,
        "max_age": 50
      }
    }
  }'

Responses

Filtro salvo com sucesso

Bodyapplication/json

filter_idinteger

Example: 123

messagestring

Example: "Filtro salvo com sucesso"

Response

application/json

{
  "filter_id": 123,
  "message": "Filtro salvo com sucesso"
}

Listar filtros salvos de pessoas

Request

Recupera todos os filtros salvos para prospecção de pessoas

Security

ApiKeyAuth

curl -i -X GET \
  https://docs.datastone.com.br/_mock/api/prospection/filters/list_person/ \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Filtros retornados com sucesso

Bodyapplication/jsonArray [

filter_idinteger

Example: 123

filter_namestring

Example: "Executivos SP"

dataobject

Filtros salvos

created_atstring(date-time)

Example: "2023-01-15T10:30:00Z"

]

Response

application/json

[
  {
    "filter_id": 123,
    "filter_name": "Executivos SP",
    "data": {},
    "created_at": "2023-01-15T10:30:00Z"
  }
]

Listar filtros salvos de empresas

Request

Recupera todos os filtros salvos para prospecção de empresas

Security

ApiKeyAuth

curl -i -X GET \
  https://docs.datastone.com.br/_mock/api/prospection/filters/list_company/ \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Filtros retornados com sucesso

Bodyapplication/jsonArray [

filter_idinteger

Example: 456

filter_namestring

Example: "Empresas Tech RJ"

dataobject

Filtros salvos

created_atstring(date-time)

Example: "2023-01-15T10:30:00Z"

]

Response

application/json

[
  {
    "filter_id": 456,
    "filter_name": "Empresas Tech RJ",
    "data": {},
    "created_at": "2023-01-15T10:30:00Z"
  }
]

Auxiliares

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

Operations

Data Stone API (1.0)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude

Autenticação

Webhooks

Rate Limiting

Limite de Produto

Erros Comuns e Como Resolver

Erro 401 - API Key Inválida

Erro 401 - IP Não Autorizado

Erro 400 - Saldo Insuficiente

Erro 429 - Limite de Requisições Excedido

Automação com n8n — Zero Código

Por que usar?

Instalação rápida

O que está coberto

Templates prontos para importar

Use como base para suas automações

Consulta

Prospecção B2B

Enriquecimento

Prospecção

Prospecção de pessoas (contagem e job)

RequestExpand all

Responses

Was this helpful?

Prospecção de empresas (contagem e job)

RequestExpand all

Responses

Was this helpful?

Obter resultado da prospecção

Request

Responses

Was this helpful?

Salvar filtro de prospecção

Request

Responses

Was this helpful?

Listar filtros salvos de pessoas

Request

Responses

Was this helpful?

Listar filtros salvos de empresas

Request

Responses

Was this helpful?

Auxiliares

Data Stone API (1.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Request

Request