# 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 **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 ``` **Exemplos de uso:** Python: ```python import requests headers = { 'Authorization': 'Token abc123suachaveaqui' } response = requests.get('https://api.datastone.com.br/v1/saldo', headers=headers) ``` JavaScript: ```javascript fetch('https://api.datastone.com.br/v1/saldo', { headers: { 'Authorization': 'Token abc123suachaveaqui' } }) ``` cURL: ```bash 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:** ```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 ## Erros Comuns e Como Resolver ### Erro 401 - API Key Inválida ```json { "detail": "Verifique o token informado." } ``` **Causa:** A API Key está incorreta ou o formato do header está errado. **Solução:** 1. Verifique se copiou a API Key corretamente (sem espaços extras no início ou fim) 2. Confirme que o header está exatamente assim: `Authorization: Token sua-api-key` 3. Se necessário, gere uma nova API Key no painel --- ### Erro 401 - IP Não Autorizado ```json { "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:** 1. Copie o IP que aparece na mensagem de erro 2. Acesse o painel da Data Stone 3. Vá em **Meu Perfil > Whitelist de IPs** 4. Adicione o IP copiado 5. Aguarde alguns segundos e tente novamente --- ### Erro 400 - Saldo Insuficiente ```json { "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 ```json { "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 n8n **Use toda a API da Data Stone sem escrever uma linha de código.** Temos um **nó comunitário oficial** para o [n8n](https://n8n.io/) — 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 1. No n8n, acesse **Settings > Community Nodes** 2. Clique em **Install a community node** 3. Digite `n8n-nodes-datastone` 4. Clique em **Install** 5. Crie uma credencial **Data Stone API** e cole sua API Key 6. 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](https://github.com/Data-Stone/n8n-nodes-datastone/tree/main/n8n_examples)** Version: 1.0 ## Servers Servidor de Produção ``` https://api.datastone.com.br/v1 ``` ## Security ### ApiKeyAuth Informe sua API Key no formato: **Token sua-api-key** Exemplo: `Token abc123suachaveaqui` Dica: Ao copiar a API Key no painel, ela já vem no formato correto. Basta colar aqui. 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. Parâmetros de entrada (pelo menos um é obrigatório): url_linkedin, email, cpf ou id_pessoa. 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 (com status_email validado), 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 Webhook: O payload enviado ao webhook segue o mesmo schema do webhook do endpoint individual (/b2b/persons/enrich), com múltiplos itens no array contatos. ### 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 (com status_email validado), website oficial - Informações: setor, descrição, número de funcionários, links públicos - Estrutura corporativa: sócios, administradores, percentuais de participação, CPF real dos sócios/funcionários (não mascarado) - 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 Webhook: O payload enviado ao webhook segue o mesmo schema do webhook do endpoint individual (/b2b/companies/enrich), com múltiplos itens no array contatos. ## 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.