مرجع واجهة برمجة تطبيقات BasedOnB
أتمتة استخراج العملاء المحتملين من خرائط جوجل، وإدارة الـ webhooks، والتكامل مع أدوات إدارة علاقات العملاء أو أتمتة سير العمل.
البدء السريع
curl https://www.basedonb.com/api/v1/account \
-H "Authorization: Bearer bdb_live_YOUR_KEY_HERE"المصادقة
جميع طلبات API (باستثناء GET /api/v1/health) تتطلب مفتاح API. أنشئ واحدًا من الإعدادات ← مفاتيح API.
مرر مفتاحك بإحدى طريقتين:
ترويسة Authorization (موصى به)
Authorization: Bearer bdb_live_...
ترويسة X-API-Key
X-API-Key: bdb_live_...
عنوان URL الأساسي
https://www.basedonb.com/api/v1
حدود المعدل
100 طلب / دقيقة لكل مفتاح API. تجاوز ذلك يُرجع 429 Too Many Requests.
نقاط النهاية
الصحة
الحساب
عمليات الاستخراج
البيانات الجغرافية
ابحث عن قيم الدولة / الولاية / المدينة التي تقبلها واجهة Scrapes. تتبع الولايات تنسيق رمز GeoNames المنقّط (US.TX, TR.34, DE.02). الدول التي ليس لديها تقسيم فرعي تُرجع مصفوفة states فارغة — أرسل تلك المهام مع country فقط.
الأرصدة والفوترة
الـ Webhooks
تسلّم الـ webhooks إشعارات الأحداث في الوقت الفعلي إلى نقطة النهاية الخاصة بك. كل طلب يتضمن ترويسة X-Webhook-Signature: sha256=<hex> للتحقق.
حمولة الـ Webhook
مثال على حمولة scrape.done تُسلّم إلى نقطة النهاية الخاصة بك:
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
}
}التحقق من توقيعات الـ Webhook
تحقق من ترويسة X-Webhook-Signature للتأكد من أن الطلبات واردة من BasedOnB. اعثر على سر الـ webhook الخاص بك في الإعدادات ← 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 });
}إدارة مفاتيح API
رموز الخطأ
| حالة HTTP | الرمز | الوصف |
|---|---|---|
| 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 |
تنسيق استجابة الخطأ:
{
"error": {
"code": "insufficient_credits",
"message": "Not enough credits. You have 3 but need 50."
}
}جاهز للبناء؟
أنشئ أول مفتاح API لك من الإعدادات وابدأ الاستخراج خلال دقائق.