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

Autenticação: Todas as requisições requerem uma API Key no header Authorization.

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

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

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

Obter estrutura de filtros B2B

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
{}

Obter opções de filtros B2B

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
{}

Buscar pessoas B2B

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": [
    { … }
  ]
}

Enriquecer pessoa (individual)

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
}

Enriquecer pessoas em lote

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
}

Buscar empresas B2B

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": [
    { … }
  ]
}

Enriquecer empresa (individual)

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",
      "empresa_id": 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
}

Enriquecer empresas em lote

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[].​empresa_idinteger
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",
        "empresa_id": 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
}

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