Skip to content
/
Obter cidades

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

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

Listar perfis de prospecção

Request

Retorna lista de perfis disponíveis para prospecção de pessoas.

Perfis são conjuntos predefinidos de características demográficas e comportamentais.

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

Responses

Perfis retornados com sucesso

Bodyapplication/json
nextstring or null

URL da próxima página (null se não houver)

Example: null
previousstring or null

URL da página anterior (null se não houver)

Example: null
countinteger

Total de perfis disponíveis

Example: 14
page_sizeinteger

Tamanho da página

Example: 20
resultsArray of objects

Lista de perfis

Response
application/json
{
  "next": null,
  "previous": null,
  "count": 14,
  "page_size": 20,
  "results": [
    { … }
  ]
}

Obter cidades

Request

Retorna cidades com base em critérios de pesquisa.

Formato de resposta: "Cidade - UF" (ex: "São Paulo - SP")

IMPORTANTE: O valor name retornado é o que deve ser enviado para prospecção.

Security
ApiKeyAuth
Query
namestring

Filtro por nome da cidade

Example: name=São Paulo
statestring

Filtro por estado (sigla UF)

Example: state=SP
curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/geo/city?name=S%C3%A3o+Paulo&state=SP' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Cidades retornadas com sucesso

Bodyapplication/jsonArray [
namestring

Nome da cidade no formato "Cidade - UF"

Example: "São Paulo - SP"
]
Response
application/json
[
  {
    "name": "São Paulo - SP"
  }
]

Obter bairros

Request

Retorna bairros com base em critérios de pesquisa.

Formato de resposta: "Bairro - Cidade - UF"

Security
ApiKeyAuth
Query
namestring

Filtro por nome do bairro

citystring

Filtro por cidade

statestring

Filtro por estado (sigla UF)

curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/geo/neighborhood?name=string&city=string&state=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Bairros retornados com sucesso

Bodyapplication/jsonArray [
namestring

Nome no formato "Bairro - Cidade - UF"

Example: "Distrito de Roselândia - Bela Vista de Goiás - GO"
]
Response
application/json
[
  {
    "name": "Distrito de Roselândia - Bela Vista de Goiás - GO"
  }
]

Obter profissões (CBO)

Request

Retorna ocupações baseadas na Classificação Brasileira de Ocupações (CBO).

Suporta busca por código CBO ou descrição da profissão.

IMPORTANTE: O code retornado é o que deve ser usado em requisições de prospecção.

Security
ApiKeyAuth
Query
codestring

Código CBO

Example: code=999999
descriptionstring

Descrição da profissão

Example: description=EMPRESÁRIO
curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/cbo?code=999999&description=EMPRES%C3%81RIO' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Profissões retornadas com sucesso

Bodyapplication/jsonArray [
codestring

Código CBO a ser usado em prospecção

Example: "999999"
descriptionstring

Descrição da profissão

Example: "EMPRESÁRIO"
]
Response
application/json
[
  {
    "code": "999999",
    "description": "EMPRESÁRIO"
  }
]

Obter CNAEs

Request

Retorna classificações CNAE (Classificação Nacional de Atividades Econômicas).

Aceita código CNAE ou descrição.

IMPORTANTE: O code retornado é o que deve ser enviado para prospecção.

Security
ApiKeyAuth
Query
codestring

Código CNAE

Example: code=6201500
descriptionstring

Descrição do CNAE

Example: description=Desenvolvimento de software
curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/cnae?code=6201500&description=Desenvolvimento+de+software' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

CNAEs retornados com sucesso

Bodyapplication/jsonArray [
codestring

Código CNAE para usar em prospecção

Example: "6201500"
descriptionstring

Descrição detalhada do CNAE

Example: "Desenvolvimento de programas de computador sob encomenda"
]
Response
application/json
[
  {
    "code": "6201500",
    "description": "Desenvolvimento de programas de computador sob encomenda"
  }
]

Obter setores CNAE

Request

Retorna informações de setor CNAE.

Suporta filtro por código ou descrição do setor.

IMPORTANTE: A description retornada é o que deve ser enviada para prospecção.

Security
ApiKeyAuth
Query
codestring

Código do setor CNAE

descriptionstring

Descrição do setor

Example: description=Tecnologia
curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/sector/cnae?code=string&description=Tecnologia' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Setores retornados com sucesso

Bodyapplication/jsonArray [
codestring

Código do setor CNAE

Example: "62"
descriptionstring

Descrição a ser usada em prospecção

Example: "Tecnologia da Informação"
]
Response
application/json
[
  {
    "code": "62",
    "description": "Tecnologia da Informação"
  }
]