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

Consultar saldo da conta

Request

Retorna informações de saldo e créditos disponíveis na conta por produto

Security

ApiKeyAuth

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

Responses

Saldo retornado com sucesso

Bodyapplication/json

balanceobject

is_posboolean

Indica se a conta é pós-paga

Example: false

Response

application/json

{
  "balance": {
    "wallet": { … },
    "credits": [ … ]
  },
  "is_pos": false
}

Consultar informações de pessoas físicas

Request

Busca informações detalhadas de pessoa física por CPF

Security

ApiKeyAuth

Query

cpfstring^\d{11}$required

CPF da pessoa (apenas números)

Example: cpf=12345678901

fieldsstring

Campos específicos a retornar (separados por vírgula)

Example: fields=name,cpf,emails,addresses

curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/persons/?cpf=12345678901&fields=name%2Ccpf%2Cemails%2Caddresses' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Informações da pessoa retornadas com sucesso

Bodyapplication/jsonArray [

cpfstring

Example: "11111111111"

namestring

Example: "FULANO DE TAL EXEMPLO"

mother_namestring

Example: "MARIA EXEMPLO"

birthdaystring(date)

Example: "1993-01-01"

agestring

Example: "30"

genderstring

Enum"M""F"

Example: "M"

signstring

Example: "Capricórnio"

registry_situationstring

Example: "REGULAR"

pepboolean

Example: false

pep_typestring

Example: ""

possibly_deadboolean

Example: false

retiredboolean

Example: false

bolsa_familiaboolean

Example: false

estimated_incomestring

Example: "ATÉ R$ 1.000,00"

cbo_codestring

Example: "999999"

cbo_descriptionstring

Example: "EMPRESÁRIO"

rgstring or null

addressesArray of objects

emailsArray of objects

mobile_phonesArray of objects

land_linesArray of objects

family_personsArray of objects

related_companiesArray of objects

employerArray of objects

ipstring

Example: "127.0.0.1"

planstring

Example: "Consulta Premium"

]

Response

application/json

[
  {
    "cpf": "11111111111",
    "name": "FULANO DE TAL EXEMPLO",
    "mother_name": "MARIA EXEMPLO",
    "birthday": "1993-01-01",
    "age": "30",
    "gender": "M",
    "sign": "Capricórnio",
    "registry_situation": "REGULAR",
    "pep": false,
    "pep_type": "",
    "possibly_dead": false,
    "retired": false,
    "bolsa_familia": false,
    "estimated_income": "ATÉ R$ 1.000,00",
    "cbo_code": "999999",
    "cbo_description": "EMPRESÁRIO",
    "rg": "string",
    "addresses": [ … ],
    "emails": [ … ],
    "mobile_phones": [ … ],
    "land_lines": [ … ],
    "family_persons": [ … ],
    "related_companies": [ … ],
    "employer": [ … ],
    "ip": "127.0.0.1",
    "plan": "Consulta Premium"
  }
]

Busca avançada de pessoas

Request

Buscar pessoas por nome, email, telefone, nome da mãe ou endereço.

Permite buscas mais flexíveis sem necessidade de CPF.

Security

ApiKeyAuth

Query

namestring

Nome da pessoa

Example: name=JOAO SILVA

emailstring

Email da pessoa

Example: email=joao@exemplo.com

phonestring

Telefone da pessoa

Example: phone=11987654321

motherstring

Nome da mãe

Example: mother=MARIA SILVA

zip_codestring

CEP

Example: zip_code=01310100

addressstring

Nome da rua/avenida

Example: address=AVENIDA PAULISTA

address_numberstring

Número do endereço

Example: address_number=1000

ufstring^[A-Z]{2}$

Estado (sigla UF)

Example: uf=SP

curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/persons/search/?name=JOAO+SILVA&email=joao%40exemplo.com&phone=11987654321&mother=MARIA+SILVA&zip_code=01310100&address=AVENIDA+PAULISTA&address_number=1000&uf=SP' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Pessoas encontradas com sucesso

Bodyapplication/jsonArray [

object

Dados da pessoa (mesmo schema do /persons)

]

Response

application/json

[
  {}
]

Busca de pessoas com wildcard

Request

Busca por nome com suporte a caractere curinga (*).

Use o asterisco (*) para representar qualquer sequência de caracteres.

Exemplo: name=JOAO*SILVA encontra "JOAO DA SILVA", "JOAO PEDRO SILVA", etc.

Security

ApiKeyAuth

Query

namestringrequired

Nome da pessoa (use * como wildcard)

Example: name=MARIA*

statestring^[A-Z]{2}$

Estado (sigla UF)

Example: state=SP

citystring

Cidade

Example: city=SAO PAULO

curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/persons/advanced-search/?name=MARIA*&state=SP&city=SAO+PAULO' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Pessoas encontradas com sucesso

Bodyapplication/jsonArray [

object

Dados da pessoa

]

Response

application/json

[
  {}
]

Consultar informações de empresas

Request

Busca informações detalhadas de empresa por CNPJ

Security

ApiKeyAuth

Query

cnpjstring^\d{14}$required

CNPJ da empresa (apenas números)

Example: cnpj=12345678000199

fieldsstring

Campos específicos a retornar (separados por vírgula)

Example: fields=company_name,cnpj,emails,partners

curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/companies/?cnpj=12345678000199&fields=company_name%2Ccnpj%2Cemails%2Cpartners' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Informações da empresa retornadas com sucesso

Bodyapplication/jsonArray [

cnpjstring

Example: "12345678000199"

company_namestring

Example: "FULANO DE TAL EXEMPLO"

trading_namestring

Example: "EMPRESA EXEMPLO"

creation_datestring(date)

Example: "2022-01-01"

agestring

Example: "3 anos 3 meses"

business_sizestring

Example: "ME"

city_ufstring

Example: "CIDADE EXEMPLO, EX"

cnae_codeinteger

Example: 9511800

cnae_descriptionstring

Example: "Reparação e manutenção de computadores e de equipamentos periféricos"

registry_situationstring

Example: "ATIVA"

addressesArray of objects

branch_officesArray of objects

partnersArray of objects

Lista de sócios da empresa

emailsArray of objects

land_linesArray of objects

mobile_phonesArray of objects

]

Response

application/json

[
  {
    "cnpj": "12345678000199",
    "company_name": "FULANO DE TAL EXEMPLO",
    "trading_name": "EMPRESA EXEMPLO",
    "creation_date": "2022-01-01",
    "age": "3 anos 3 meses",
    "business_size": "ME",
    "city_uf": "CIDADE EXEMPLO, EX",
    "cnae_code": 9511800,
    "cnae_description": "Reparação e manutenção de computadores e de equipamentos periféricos",
    "registry_situation": "ATIVA",
    "addresses": [ … ],
    "branch_offices": [ … ],
    "partners": [ … ],
    "emails": [ … ],
    "land_lines": [ … ],
    "mobile_phones": [ … ]
  }
]

Buscar empresas

Request

Buscar empresas por razão social, email, domínio, CEP ou telefone.

Permite buscas sem necessidade de CNPJ.

Security

ApiKeyAuth

Query

razao_socialstring

Razão social da empresa

Example: razao_social=EMPRESA EXEMPLO LTDA

emailstring

Email da empresa

Example: email=contato@empresa.com

domainstring

Domínio do site da empresa

Example: domain=empresa.com.br

cepstring

CEP da empresa

Example: cep=01310100

phonestring

Telefone da empresa

Example: phone=1133334444

ufstring^[A-Z]{2}$

Estado (sigla UF)

Example: uf=SP

curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/company/list/?razao_social=EMPRESA+EXEMPLO+LTDA&email=contato%40empresa.com&domain=empresa.com.br&cep=01310100&phone=1133334444&uf=SP' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Empresas encontradas com sucesso

Bodyapplication/jsonArray [

object

Dados da empresa (mesmo schema do /companies)

]

Response

application/json

[
  {}
]

Buscar matriz e filiais

Request

Localizar matriz e todas as filiais de uma empresa a partir de qualquer CNPJ do grupo.

Retorna informações de todas as unidades (matriz + filiais).

Security

ApiKeyAuth

Query

cnpjstring^\d{14}$required

CNPJ da empresa (matriz ou filial)

Example: cnpj=12345678000199

curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/company/search/filial/?cnpj=12345678000199' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Matriz e filiais encontradas com sucesso

Bodyapplication/json

matrizobject

Dados da matriz

filiaisArray of objects

Lista de filiais

Response

application/json

{
  "matriz": {},
  "filiais": [
    {}
  ]
}

Validar status de contato WhatsApp

Request

Verifica se um número de telefone está ativo no WhatsApp.

IMPORTANTE: Os campos ddd e phone devem ser enviados separadamente, sem formatação (sem traços ou espaços).

Security

ApiKeyAuth

Query

dddstring^\d{2}$required

DDD do telefone (exatamente 2 dígitos)

Example: ddd=11

phonestring^\d{1,9}$required

Número do telefone (até 9 dígitos, apenas números)

Example: phone=987654321

curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/whatsapp/search/?ddd=11&phone=987654321' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Status do WhatsApp retornado com sucesso

Bodyapplication/json

statusstring

Enum"ATIVO""INATIVO"

Example: "ATIVO"

Response

application/json

{
  "status": "ATIVO"
}

Validar múltiplos números WhatsApp

Request

Verifica o status de múltiplos números de telefone no WhatsApp em uma única requisição.

Processamento assíncrono com callback.

Limite: Até 1000 números por requisição

Security

ApiKeyAuth

Bodyapplication/jsonrequired

phonesArray of strings<= 1000 itemsrequired

Array de números completos (até 11 dígitos cada)

Example: ["11987654321","21987654321"]

callback_urlstring

URL para receber callback com resultados

Example: "https://seusite.com/callback"

curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/whatsapp/batch/ \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "phones": [
      "11987654321",
      "21987654321"
    ],
    "callback_url": "https://seusite.com/callback"
  }'

Responses

Job de validação criado com sucesso

Bodyapplication/json

job_idinteger

ID do job de processamento

Example: 12345

statusstring

Example: "requested"

total_numbersinteger

Total de números a serem validados

Example: 100

Response

application/json

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

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

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

Consultar saldo da conta

Request

Responses

Was this helpful?

Consultar informações de pessoas físicas

Request

Responses

Was this helpful?

Busca avançada de pessoas

Request

Responses

Was this helpful?

Busca de pessoas com wildcard

Request

Responses

Was this helpful?

Consultar informações de empresas

Request

Responses

Was this helpful?

Buscar empresas

Request

Responses

Was this helpful?

Buscar matriz e filiais

Request

Responses

Was this helpful?

Validar status de contato WhatsApp

Request

Responses

Was this helpful?

Validar múltiplos números WhatsApp

Request

Responses

Was this helpful?

Prospecção B2B

Enriquecimento

Prospecção

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