# Data Stone API 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:** ```json { "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 Version: 1.0 ## Servers Servidor de Produção ``` https://api.datastone.com.br/v1 ``` ## Security ### ApiKeyAuth API Key de autenticação. Formato: `Authorization: ` Type: apiKey In: header Name: Authorization ## Download OpenAPI description [Data Stone API](https://docs.datastone.com.br/_bundle/api.yaml) ## Consulta Operações de consulta direta para pessoas físicas (CPF), empresas (CNPJ), validação de WhatsApp e verificação de saldo. ### Consultar saldo da conta - [GET /balance](https://docs.datastone.com.br/api/consulta/get_balance.md): Retorna informações de saldo e créditos disponíveis na conta por produto ### Consultar informações de pessoas físicas - [GET /persons](https://docs.datastone.com.br/api/consulta/get_persons.md): Busca informações detalhadas de pessoa física por CPF ### Busca avançada de pessoas - [GET /persons/search](https://docs.datastone.com.br/api/consulta/get_persons_search.md): Buscar pessoas por nome, email, telefone, nome da mãe ou endereço. Permite buscas mais flexíveis sem necessidade de CPF. ### Busca de pessoas com wildcard - [GET /persons/advanced-search](https://docs.datastone.com.br/api/consulta/get_persons_advanced_search.md): 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. ### Consultar informações de empresas - [GET /companies](https://docs.datastone.com.br/api/consulta/get_companies.md): Busca informações detalhadas de empresa por CNPJ ### Buscar empresas - [GET /company/list](https://docs.datastone.com.br/api/consulta/get_company_list.md): Buscar empresas por razão social, email, domínio, CEP ou telefone. Permite buscas sem necessidade de CNPJ. ### Buscar matriz e filiais - [GET /company/search/filial](https://docs.datastone.com.br/api/consulta/get_company_filial.md): 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). ### Validar status de contato WhatsApp - [GET /whatsapp/search](https://docs.datastone.com.br/api/consulta/get_whatsapp_status.md): 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). ### Validar múltiplos números WhatsApp - [POST /whatsapp/batch](https://docs.datastone.com.br/api/consulta/post_whatsapp_batch.md): 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 ## 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. ### Obter estrutura de filtros B2B - [GET /b2b/filter-structure](https://docs.datastone.com.br/api/prospeccao-b2b/get_filter_structure.md): 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. ### Obter opções de filtros B2B - [GET /b2b/filter-options](https://docs.datastone.com.br/api/prospeccao-b2b/get_filter_options.md): 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"} ### Busca com autocomplete - [GET /b2b/search](https://docs.datastone.com.br/api/prospeccao-b2b/get_autocomplete_search.md): Busca em tempo real por diferentes tipos de dados com autocomplete. Parâmetros de busca disponíveis: - nome_empresa - Nomes de empresas (LinkedIn, razão social, nome fantasia) - Limite: 50 - localizacao - Cidades (passar UF do estado) - Sem limite - setor - Setor empresarial - Limite: 50 - cargo - Cargos/funções - Limite: 50 - atividade_cnae - Atividades CNAE - Limite: 50 - natureza_juridica - Natureza jurídica - Limite: 50 - especialidade - Especialidades - Limite: 50 ### Buscar pessoas B2B - [POST /b2b/persons](https://docs.datastone.com.br/api/prospeccao-b2b/post_b2b_persons.md): 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. ### Enriquecer pessoa (individual) - [POST /b2b/persons/enrich](https://docs.datastone.com.br/api/prospeccao-b2b/post_b2b_person_enrich.md): 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). ### Enriquecer pessoas em lote - [POST /b2b/persons/enrich/bulk](https://docs.datastone.com.br/api/prospeccao-b2b/post_b2b_persons_enrich_bulk.md): 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 ### Buscar empresas B2B - [POST /b2b/companies](https://docs.datastone.com.br/api/prospeccao-b2b/post_b2b_companies.md): 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. ### Enriquecer empresa (individual) - [POST /b2b/companies/enrich](https://docs.datastone.com.br/api/prospeccao-b2b/post_b2b_company_enrich.md): 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 ### Enriquecer empresas em lote - [POST /b2b/companies/enrich/bulk](https://docs.datastone.com.br/api/prospeccao-b2b/post_b2b_companies_enrich_bulk.md): Enriquecimento em massa de empresas com processamento assíncrono. Custo: 1 crédito por registro enriquecido Dados retornados: Mesmos do enriquecimento individual ## Enriquecimento Operações de enriquecimento de dados em lote com layouts personalizáveis e processamento assíncrono. ### Listar layouts de enriquecimento - [GET /enrichment/layouts](https://docs.datastone.com.br/api/enriquecimento/get_enrichment_layouts.md): Retorna lista de layouts disponíveis para o processo de enriquecimento. Permite visualizar opções de formatação ao criar requisições. ### Solicitar enriquecimento - [POST /enrichment](https://docs.datastone.com.br/api/enriquecimento/post_enrichment.md): 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"] ### Obter resultado do enriquecimento - [GET /enrichment/{id}/result](https://docs.datastone.com.br/api/enriquecimento/get_enrichment_result.md): Recupera o resultado de uma requisição de enriquecimento. Se webhook foi configurado, o status do processo será enviado automaticamente. ## Prospecção Operações de prospecção com filtros geográficos e profissionais, incluindo contagem e geração de jobs de prospecção. ### Prospecção de pessoas (contagem e job) - [POST /persons/prospect](https://docs.datastone.com.br/api/prospeccao/post_persons_prospect.md): 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 ### Prospecção de empresas (contagem e job) - [POST /company/prospect](https://docs.datastone.com.br/api/prospeccao/post_company_prospect.md): 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 ### Obter resultado da prospecção - [GET /prospection/{job_id}/result](https://docs.datastone.com.br/api/prospeccao/get_prospection_result.md): Recupera o resultado de um job de prospecção. Se webhook foi configurado, o status do processo será enviado automaticamente. ### Salvar filtro de prospecção - [POST /prospection/filters](https://docs.datastone.com.br/api/prospeccao/post_prospection_filters.md): Salva um conjunto de filtros para reutilização posterior. Permite armazenar filtros complexos de pessoas ou empresas para uso recorrente. ### Listar filtros salvos de pessoas - [GET /prospection/filters/list_person](https://docs.datastone.com.br/api/prospeccao/get_prospection_filters_person.md): Recupera todos os filtros salvos para prospecção de pessoas ### Listar filtros salvos de empresas - [GET /prospection/filters/list_company](https://docs.datastone.com.br/api/prospeccao/get_prospection_filters_company.md): Recupera todos os filtros salvos para prospecção de empresas ## Auxiliares Dados auxiliares como CNAE, CBO, geolocalização (estados, cidades, bairros) e setores empresariais. ### Listar perfis de prospecção - [GET /persons/prospect/profile](https://docs.datastone.com.br/api/auxiliares/get_persons_prospect_profile.md): Retorna lista de perfis disponíveis para prospecção de pessoas. Perfis são conjuntos predefinidos de características demográficas e comportamentais. ### Obter cidades - [GET /geo/city](https://docs.datastone.com.br/api/auxiliares/get_cities.md): 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. ### Obter bairros - [GET /geo/neighborhood](https://docs.datastone.com.br/api/auxiliares/get_neighborhoods.md): Retorna bairros com base em critérios de pesquisa. Formato de resposta: "Bairro - Cidade - UF" ### Obter profissões (CBO) - [GET /cbo](https://docs.datastone.com.br/api/auxiliares/get_cbo.md): 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. ### Obter CNAEs - [GET /cnae](https://docs.datastone.com.br/api/auxiliares/get_cnae.md): 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. ### Obter setores CNAE - [GET /sector/cnae](https://docs.datastone.com.br/api/auxiliares/get_sector_cnae.md): 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.