التوثيق
توثيق BasedOnB
أتمتة استخراج العملاء المحتملين من خرائط جوجل عبر REST API، أو اتصل بمساعدي الذكاء الاصطناعي مباشرةً عبر خادم MCP.
جاهز للبناء؟
أنشئ أول مفتاح API لك من الإعدادات وابدأ الاستخراج خلال دقائق.
أتمتة استخراج العملاء المحتملين من خرائط جوجل عبر REST API، أو اتصل بمساعدي الذكاء الاصطناعي مباشرةً عبر خادم MCP.
أنشئ أول مفتاح API لك من الإعدادات وابدأ الاستخراج خلال دقائق.
curl https://www.basedonb.com/api/v1/account \
-H "Authorization: Bearer bdb_live_YOUR_KEY_HERE"جميع طلبات API (باستثناء GET /health) تتطلب مفتاح API. أنشئ واحدًا من API & Webhooks ← مفاتيح API.
مرر مفتاحك بإحدى طريقتين:
ترويسة Authorization (موصى به)
Authorization: Bearer bdb_live_...
ترويسة X-API-Key
X-API-Key: bdb_live_...
استخدم REST API من خادم خلفي موثوق. طلبات المتصفح عبر النطاقات معطلة عمدًا، ويجب عدم كشف مفاتيح API في شفرة العميل.
تتضمن استجابات REST الترويسة X-Request-Id. وتتضمن الطلبات الموثقة أيضًا RateLimit-Limit وRateLimit-Remaining وRateLimit-Reset؛ وتتضمن الطلبات المحدودة Retry-After.
https://www.basedonb.com/api/v1
100 طلب / دقيقة لكل مفتاح API. تجاوز ذلك يُرجع 429.
ابحث عن قيم الدولة / الولاية / المدينة التي تقبلها واجهة Scrapes. تتبع الولايات تنسيق رمز GeoNames المنقّط (US.CA, TR.34, DE.BE). الدول التي ليس لديها تقسيم فرعي تُرجع مصفوفة states فارغة. أرسل تلك المهام مع country فقط.
تسلّم الـ webhooks إشعارات الأحداث في الوقت الفعلي إلى نقطة النهاية الخاصة بك. كل طلب يتضمن ترويسة X-Webhook-Signature للتحقق.
API keys are created and revoked only from the authenticated dashboard. Choose the minimum required scopes when creating a key: mcp, scrapes:read, scrapes:write, account:read, geodata:read, webhooks:read, and webhooks:write. Keys cannot create or manage other keys through the public API.
مثال على حمولة scrape.done تُسلّم إلى نقطة النهاية الخاصة بك:
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"
}
}تحقق من ترويسة X-Webhook-Signature للتأكد من أن الطلبات واردة من BasedOnB. احفظ سر التوقيع الذي يظهر مرة واحدة فقط عند إنشاء الـ webhook أو تدويره.
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 });
}أعد أي حالة 2xx لتأكيد التسليم. تُعاد محاولة التسليم الفاشل بعد دقيقة و5 دقائق و30 دقيقة وساعتين، وبحد أقصى 5 محاولات. خزّن X-Webhook-Event-Id وتجاهل الأحداث المعالجة سابقًا. يمثل الطابع الزمني وقت إنشاء الحدث ولا يتغير عند إعادة المحاولة؛ لا ترفض محاولة صحيحة لمجرد أن الطابع قديم.
| حالة HTTP | الرمز | الوصف |
|---|---|---|
| 400 | bad_request | Invalid request parameters |
| 401 | unauthorized | Missing, invalid, expired, or revoked credential |
| 402 | insufficient_credits | Not enough credits to start a scrape |
| 402 | payment_required | Subscription payment is past due |
| 403 | forbidden | Credential is missing the required scope |
| 404 | not_found | Resource not found |
| 409 | conflict | Idempotency-key conflict or resource limit conflict |
| 429 | rate_limited | Per-key request limit, webhook-test limit, or open scrape capacity limit exceeded |
| 500 | internal_error | Unexpected server error |
| 503 | service_unavailable | A required dependency is unavailable |
تنسيق استجابة الخطأ:
{
"error": {
"code": "insufficient_credits",
"message": "Not enough credits. You have 3 but need 50."
}
}يمكن للعملاء الداعمين لـ OAuth الاتصال دون نسخ مفتاح API طويل الأجل. يستخدم BasedOnB مسار Authorization Code مع PKCE، ويدوّر رموز التحديث، ويتيح إلغاء الوصول من لوحة التحكم.
https://www.basedonb.com/api/mcpتتوفر الموصلات البعيدة المخصصة في Claude Pro وMax وTeam وEnterprise. في Claude Desktop أضفها من Settings → Connectors.
https://www.basedonb.com/api/mcpتتوفر تطبيقات MCP المخصصة الكاملة، بما فيها أدوات الكتابة في BasedOnB، حاليًا على الويب لمساحات ChatGPT Business وEnterprise وEdu عندما يفعّل المسؤول وضع المطور.
https://www.basedonb.com/api/mcpيدعم وضع المطور في ChatGPT Pro أدوات MCP البعيدة للقراءة والجلب، لكن BasedOnB يتضمن أيضًا أدوات كتابة مثل submit_scrape وcancel_scrape. لا تدعم Plus تطبيقات MCP المخصصة. يعتمد التوفر على OpenAI وسياسة مساحة العمل.
استخدم عقدة MCP Client Tool المدمجة بالإصدار 1.2 أو أحدث.
https://www.basedonb.com/api/mcpاربط BasedOnB مع Claude أو ChatGPT أو n8n أو Cursor أو أي عميل MCP يدعم Streamable HTTP. تستخدم اتصالات OAuth ومفاتيح API أرصدة الحساب نفسها وتوفر 10 أدوات.
للعملاء المحليين ذوي بيانات الاعتماد الثابتة، أنشئ مفتاح API بأقل نطاقات لازمة من API & Webhooks ثم استخدم عنوان MCP وترويسة Authorization أدناه. في Claude Desktop تُضاف الخوادم البعيدة من Settings → Connectors وليس عبر claude_desktop_config.json.
اختر عميلك وانسخ المقتطف. استبدل المفتاح النائب بمفتاحك الخاص.
claude mcp add --transport http basedonb https://www.basedonb.com/api/mcp \
--header "Authorization: Bearer bdb_live_xxxxxxxxxxxxxxxxx"نفّذ الأمر داخل المشروع الذي تريد استخدام BasedOnB فيه. يحفظه Claude Code افتراضيًا في نطاق المشروع المحلي؛ استخدم --scope user لجميع المشاريع.
تعيد كل أداة البيانات نفسها أيضًا ضمن structuredContent.data إلى جانب محتوى JSON النصي. تضبط الأخطاء isError=true وتتضمن رمز خطأ API وحالة HTTP.
تقبل نقطة MCP إما رمز وصول OAuth بنطاق mcp أو مفتاح API من نوع bdb_live_… يتضمن هذا النطاق.
طرق المصادقة المدعومة:
Authorization: Bearer eyJ...Authorization: Bearer bdb_live_...يطبق BasedOnB مسار Authorization Code مع PKCE، والتسجيل الديناميكي للعملاء (RFC 7591)، وبيانات خادم التفويض (RFC 8414)، وبيانات المورد المحمي (RFC 9728). نطاق OAuth الوحيد هو mcp.
GET /.well-known/oauth-protected-resource — بيانات المورد المحمي (RFC 9728).GET /.well-known/oauth-authorization-server — بيانات خادم التفويض (RFC 8414).POST /oauth/register — تسجيل ديناميكي لعميل عام؛ يتطلب PKCE S256.GET /oauth/authorize — نقطة تسجيل الدخول والموافقة لمسار Authorization Code.POST /oauth/token — تستبدل الرمز أو رمز التحديث الدوّار برموز وصول.POST /oauth/revoke — تلغي رمز التحديث وعائلة الرموز التابعة له (RFC 7009).رموز الوصول هي JWT بتوقيع HS256 وصلاحية 15 دقيقة. رموز التحديث معتمة وتنتهي بعد 30 يومًا وتدور عند كل استخدام، ويُلغى كامل أفراد العائلة عند اكتشاف إعادة الاستخدام. تنتهي رموز التفويض بعد 60 ثانية.