Referencia de API BasedOnB
Automatiza la extracción de leads de Google Maps, gestiona webhooks e integra con tu CRM o herramientas de automatización.
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 /api/v1/health) requieren una clave API. Genera una desde Ajustes → Claves API.
Pasa tu clave de una de dos maneras:
Cabecera Authorization (recomendado)
Authorization: Bearer bdb_live_...
Cabecera X-API-Key
X-API-Key: bdb_live_...
URL Base
https://www.basedonb.com/api/v1
Límites de tasa
100 solicitudes / minuto por clave API. Superarlo devuelve 429 Too Many Requests.
Endpoints
Salud
Cuenta
Scrapes
Geodatos
Busca los valores de país / estado / ciudad aceptados por la API de Scrapes. Los estados siguen el formato de código con puntos de GeoNames (US.TX, TR.34, DE.02). Los países sin subdivisión devuelven un array states vacío — envía esos trabajos solo con country.
Créditos y Facturación
Webhooks
Los webhooks entregan notificaciones de eventos en tiempo real a tu endpoint. Cada solicitud incluye una cabecera X-Webhook-Signature: sha256=<hex> para verificación.
Carga útil del webhook
Ejemplo de carga útil scrape.done entregada a tu endpoint:
POST https://your-server.com/webhook
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Event-Type: scrape.done
User-Agent: BasedOnB-Webhook/1.0
{
"event": "scrape.done",
"created_at": "2026-01-15T10:05:00Z",
"data": {
"scrape_id": "job-uuid",
"query": "restaurants",
"city": "Istanbul",
"country": "Turkey",
"leads_found": 47,
"credits_charged": 47
}
}Verificar firmas de webhook
Verifica la cabecera X-Webhook-Signature para asegurarte de que las solicitudes provienen de BasedOnB. Encuentra tu secreto de webhook en Ajustes → Webhooks.
import { createHmac } from "crypto";
function verifyWebhook(body: string, signature: string, secret: string): boolean {
const expected = "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
return expected === signature;
}
// In your endpoint handler:
const body = await req.text();
const sig = req.headers.get("X-Webhook-Signature") ?? "";
if (!verifyWebhook(body, sig, process.env.WEBHOOK_SECRET!)) {
return new Response("Unauthorized", { status: 401 });
}Gestión de claves API
Códigos de error
| Estado HTTP | Código | Descripción |
|---|---|---|
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | API key valid but not allowed for this resource |
| 404 | not_found | Resource not found |
| 400 | bad_request | Invalid request parameters |
| 402 | insufficient_credits | Not enough credits to start a scrape |
| 429 | rate_limited | Too many requests. Retry after 1 minute |
| 500 | internal_error | Unexpected server error |
Formato de respuesta de error:
{
"error": {
"code": "insufficient_credits",
"message": "Not enough credits. You have 3 but need 50."
}
}¿Listo para construir?
Genera tu primera clave API en Ajustes y comienza a extraer datos en minutos.