BasedOnBusiness

Documentação do BasedOnB

Automatize a extração de leads do Google Maps com a API REST ou conecte diretamente aos seus assistentes de IA com o servidor MCP.

Início Rápido

curl https://www.basedonb.com/api/v1/account \
  -H "Authorization: Bearer bdb_live_YOUR_KEY_HERE"

Autenticação

Todas as solicitações de API (exceto GET /health) exigem uma chave de API. Crie uma em API & Webhooks → Chaves de API.

Envie sua chave de uma das duas maneiras:

Cabeçalho Authorization (recomendado)

Authorization: Bearer bdb_live_...

Cabeçalho X-API-Key

X-API-Key: bdb_live_...

Use a API REST por meio de um backend confiável. Solicitações cross-origin entre navegadores estão deliberadamente desativadas; nunca exponha chaves de API em código do lado do cliente.

As respostas REST incluem X-Request-Id. Em solicitações autenticadas, também são enviados RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; em solicitações que atingem o limite, Retry-After é enviado.

URL Base

https://www.basedonb.com/api/v1

Limites de Taxa

100 solicitações por minuto por chave de API. Exceder esse limite retorna 429.

Endpoints

Saúde

Conta

Scrapes

Dados Geográficos

Consulte os valores de país / estado / cidade aceitos pela API Scrapes. Os estados seguem o formato de código de ponto GeoNames (US.CA, TR.34, DE.BE). Países sem subdivisões retornam uma matriz states vazia. Envie esses trabalhos apenas com country.

Créditos e Faturamento

Webhooks

Os webhooks entregam notificações de eventos em tempo real para o seu endpoint. Cada solicitação inclui um cabeçalho X-Webhook-Signature para verificação.

Gerenciamento de Chaves de API

As chaves de API são criadas e revogadas apenas no painel autenticado. Escolha os escopos mínimos necessários ao criar uma chave: mcp, scrapes:read, scrapes:write, account:read, geodata:read, webhooks:read e webhooks:write. As chaves não podem criar ou gerenciar outras chaves por meio da API pública.

Payload do Webhook

Exemplo de payload scrape.done entregue ao seu endpoint:

POST https://your-server.com/webhook
Content-Type: application/json
X-Webhook-Id: delivery-uuid
X-Webhook-Event-Id: event-uuid
X-Webhook-Timestamp: 2026-07-18T10:05:00Z
X-Webhook-Signature: v1=abc123...
X-Event-Type: scrape.done
User-Agent: BasedOnB-Webhook/2.0

{
  "id": "event-uuid",
  "event": "scrape.done",
  "created_at": "2026-01-15T10:05:00Z",
  "data": {
    "scrape_id": "job-uuid",
    "query": "restaurants",
    "queries": ["restaurants"],
    "city": "Istanbul",
    "country": "TR",
    "state": "TR.34",
    "state_name": "İstanbul",
    "status": "done",
    "leads_found": 47,
    "credits_charged": 47,
    "error": null,
    "results_path": "/api/v1/scrapes/job-uuid/results"
  }
}

Verificando Assinaturas de Webhook

Para garantir que as solicitações venham do BasedOnB, verifique o cabeçalho X-Webhook-Signature. Salve a chave de assinatura, que é exibida apenas uma vez ao criar o webhook ou renovar a chave.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(body: string, timestamp: string, signature: string, secret: string): boolean {
  const match = /^v1=([0-9a-f]{64})$/i.exec(signature);
  if (!match) return false;

  const expected = createHmac("sha256", secret)
    .update(timestamp + "." + body)
    .digest();
  const received = Buffer.from(match[1], "hex");
  return received.length === expected.length && timingSafeEqual(received, expected);
}

// In your endpoint handler:
const body = await req.text();
const sig = req.headers.get("X-Webhook-Signature") ?? "";
const timestamp = req.headers.get("X-Webhook-Timestamp") ?? "";
if (!verifyWebhook(body, timestamp, sig, process.env.WEBHOOK_SECRET!)) {
  return new Response("Unauthorized", { status: 401 });
}

Retorne qualquer código de status 2xx para confirmar a entrega. Entregas com falha são repetidas após 1 minuto, 5 minutos, 30 minutos e 2 horas, até no máximo 5 tentativas. Armazene o valor de X-Webhook-Event-Id e ignore eventos já processados. O timestamp é o momento em que o evento foi criado e não muda em novas tentativas; não rejeite uma nova tentativa válida apenas porque o timestamp é antigo.

Códigos de Erro

Status HTTP	Código	Descrição
400	bad_request	Parâmetros de solicitação inválidos
401	unauthorized	Credencial ausente, inválida, expirada ou revogada
402	insufficient_credits	Créditos insuficientes para iniciar uma coleta
402	payment_required	Pagamento da assinatura está atrasado
403	forbidden	A credencial não possui o escopo necessário
404	not_found	Recurso não encontrado
409	conflict	Conflito de chave de idempotência ou conflito de limite de recurso
429	rate_limited	Limite de solicitações por chave, limite de teste de webhook ou limite de capacidade de coleta aberta excedido
500	internal_error	Erro inesperado do servidor
503	service_unavailable	Uma dependência necessária está indisponível

Formato de resposta de erro:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits. You have 3 but need 50."
  }
}

Pronto para começar?

Crie sua primeira chave de API nas Configurações e comece a coletar em minutos.