BasedOnBusiness

Documentación de BasedOnB

Automatice la extracción de leads de Google Maps con la API REST o conéctela directamente a sus asistentes de IA mediante el servidor MCP.

Inicio rápido

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

Autenticación

Todas las solicitudes de API (excepto GET /health) requieren una clave de API. Créela en API y Webhooks → Claves de API.

Envíe su clave de una de estas dos formas:

Encabezado Authorization (recomendado)

Authorization: Bearer bdb_live_...

Encabezado X-API-Key

X-API-Key: bdb_live_...

Utilice la API REST a través de un backend confiable. Las solicitudes entre orígenes desde navegadores están deliberadamente deshabilitadas; nunca exponga las claves de API en código del lado del cliente.

Las respuestas REST incluyen X-Request-Id. En solicitudes autenticadas también se envían RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset; en solicitudes que alcanzan el límite se envía Retry-After.

URL base

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

Límites de velocidad

100 solicitudes por minuto por clave de API. Superar este límite devuelve 429.

Endpoints

Salud

Cuenta

Extracciones

Datos geográficos

Busque los valores de país / estado / ciudad que acepta la API de Extracciones. Los estados siguen el formato de código de puntos de GeoNames (US.CA, TR.34, DE.BE). Los países sin subdivisiones devuelven un array states vacío. Envíe estos trabajos solo con country.

Créditos y facturación

Webhooks

Los webhooks entregan notificaciones de eventos en tiempo real a su endpoint. Cada solicitud incluye un encabezado X-Webhook-Signature para verificación.

Gestión de claves de API

Las claves de API se crean y revocan únicamente desde el panel autenticado. Elija los alcances mínimos requeridos al crear una clave: mcp, scrapes:read, scrapes:write, account:read, geodata:read, webhooks:read y webhooks:write. Las claves no pueden crear ni gestionar otras claves a través de la API pública.

Carga útil del webhook

Ejemplo de carga útil scrape.done entregada a su 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"
  }
}

Verificación de firmas de webhook

Verifique el encabezado X-Webhook-Signature para asegurarse de que las solicitudes provienen de BasedOnB. Guarde la clave de firma, que se muestra solo una vez al crear el webhook o al renovar la clave.

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 });
}

Devuelva cualquier código de estado 2xx para confirmar la entrega. Las entregas fallidas se reintentan después de 1 minuto, 5 minutos, 30 minutos y 2 horas, hasta un máximo de 5 intentos. Almacene X-Webhook-Event-Id e ignore eventos ya procesados. El timestamp es el momento de creación del evento y no cambia en los reintentos; no rechace un reintento válido solo porque el timestamp sea antiguo.

Códigos de error

Estado HTTP	Código	Descripción
400	bad_request	Parámetros de solicitud no válidos
401	unauthorized	Credencial faltante, no válida, expirada o revocada
402	insufficient_credits	Créditos insuficientes para iniciar una extracción
402	payment_required	El pago de la suscripción está vencido
403	forbidden	La credencial no tiene el alcance requerido
404	not_found	Recurso no encontrado
409	conflict	Conflicto de clave de idempotencia o conflicto de límite de recursos
429	rate_limited	Límite de solicitudes por clave, límite de prueba de webhook o límite de capacidad de extracción abierta superado
500	internal_error	Error inesperado del servidor
503	service_unavailable	Una dependencia requerida no está disponible

Formato de respuesta de error:

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

¿Listo para comenzar?

Cree su primera clave de API en Configuración y comience a extraer en minutos.