مرجع واجهة برمجة تطبيقات REST

نظرة عامة

يتضمن LeadHub واجهة REST API كاملة تتيح للأدوات الخارجية قراءة بياناتك وكتابتها — العملاء المحتملون، والمسارات، والأتمتة، والنماذج والمزيد. استخدمها للتكامل مع Zapier، وإنشاء لوحات متابعة مخصصة، وربط موقعك الإلكتروني، أو أتمتة أي شيء.

عنوان URL الأساسي

تُرسَل جميع طلبات API إلى:

https://yourdomain.com/api/v1

استبدل yourdomain.com بنطاق LeadHub الفعلي الخاص بك.

المصادقة

يتطلب كل طلب (باستثناء health check) مفتاح API.

أنشئ مفاتيح API في لوحة الإدارة ضمن الإعدادات → مفاتيح API. راجع صفحة الإعدادات للحصول على التعليمات.

أدرج مفتاح API في كل طلب كرمز Bearer في رأس Authorization:

Authorization: Bearer lh_your_api_key_here

إذا أرسلت طلباً بدون مفتاح API أو بمفتاح غير صالح، فستتلقى استجابة 401 Unauthorized.

تحديد معدل الطلبات

يُقيَّد كل مفتاح API بـ 1,000 طلب في الساعة بشكل افتراضي (قابل للتكوين لكل مفتاح). إذا تجاوزت هذا الحد، ستتلقى استجابة 429 Too Many Requests.

تتضمن كل استجابة هذه الرؤوس حتى تتمكن من تتبع استخدامك:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1711580400

X-RateLimit-Reset هو طابع زمني Unix يشير إلى موعد إعادة تعيين حدّك.

التقسيم إلى صفحات

تدعم نقاط النهاية التي تُعيد قوائم السجلات التصفح بالصفحات. أضف معاملات الاستعلام التالية:

المعامل	الافتراضي	الحد الأقصى
`page`	`1`	—
`per_page`	`15`	`100`

مثال: GET /api/v1/leads?page=2&per_page=25

تنسيق الاستجابة

استجابة ناجحة

{
  "data": { ... },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 73,
    "from": 1,
    "to": 15
  },
  "links": {
    "first": "https://yourdomain.com/api/v1/leads?page=1",
    "last": "https://yourdomain.com/api/v1/leads?page=5",
    "prev": null,
    "next": "https://yourdomain.com/api/v1/leads?page=2",
    "self": "https://yourdomain.com/api/v1/leads?page=1"
  }
}

في استجابات السجل الواحد (show, create, update)، يحتوي data على كائن السجل ويُحذف meta.

استجابة خطأ

{
  "status": "error",
  "message": "The given data was invalid.",
  "code": "VALIDATION_FAILED",
  "errors": {
    "email": ["The email field must be a valid email address."]
  }
}

رموز الأخطاء الشائعة:

الرمز	حالة HTTP	المعنى
`UNAUTHORIZED`	401	مفتاح API مفقود أو غير صالح
`FORBIDDEN`	403	مفتاح API يفتقر إلى النطاق المطلوب
`NOT_FOUND`	404	السجل غير موجود
`VALIDATION_FAILED`	422	فشل التحقق من صحة بيانات الطلب
`RATE_LIMITED`	429	طلبات كثيرة جداً
`SERVER_ERROR`	500	خطأ غير متوقع في الخادم

فحص الصحة

لا يتطلب مصادقة.

GET /api/v1/health

الاستجابة:

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-03-28T09:15:00+00:00"
}

استخدم هذا للتحقق من إمكانية الوصول إلى نسخة LeadHub قبل إرسال طلبات أخرى.

العملاء المحتملون (Leads)

النطاق المطلوب: read:leads للاسترداد، write:leads للإنشاء/التحديث، delete:leads للحذف.

سرد العملاء المحتملين

GET /api/v1/leads

معاملات الاستعلام للتصفية:

المعامل	الوصف
`source`	التصفية حسب المصدر (مثلاً `facebook`، `website`)
`status`	التصفية حسب الحالة (مثلاً `new`، `contacted`، `qualified`)
`pipeline_id`	التصفية حسب معرّف المسار
`stage_id`	التصفية حسب معرّف مرحلة المسار
`assigned_user_id`	التصفية حسب معرّف المستخدم المعيّن
`tag`	التصفية حسب اسم الوسم
`search`	البحث بالاسم أو البريد الإلكتروني أو الهاتف
`created_after`	تاريخ ISO 8601 — فقط العملاء المنشؤون بعد هذا التاريخ
`created_before`	تاريخ ISO 8601 — فقط العملاء المنشؤون قبل هذا التاريخ
`starred`	`true` لإظهار العملاء المُنجَّمين فقط
`sort`	الحقل للترتيب: `created_at`، `updated_at`، `lead_score`، `first_name`، `last_name`، `email`
`direction`	`asc` أو `desc` (الافتراضي: `desc`)

الحصول على عميل محتمل

GET /api/v1/leads/{id}

إنشاء عميل محتمل

POST /api/v1/leads

جسم الطلب (JSON):

{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "[email protected]",
  "phone": "+14155551234",
  "source": "website",
  "status": "new",
  "pipeline_id": 1,
  "pipeline_stage_id": 2,
  "assigned_user_id": 5,
  "notes": "Interested in the enterprise plan.",
  "custom_fields": {
    "budget": "10000"
  },
  "tags": ["hot-lead", "enterprise"]
}

first_name مطلوب. جميع الحقول الأخرى اختيارية.

تحديث عميل محتمل

PUT /api/v1/leads/{id}
PATCH /api/v1/leads/{id}

أرسل الحقول التي تريد تحديثها فقط. نفس حقول الإنشاء.

حذف عميل محتمل

DELETE /api/v1/leads/{id}

إضافة وسم إلى عميل محتمل

POST /api/v1/leads/{id}/tags

الجسم: { "tag": "vip-client" }

إزالة وسم من عميل محتمل

DELETE /api/v1/leads/{id}/tags/{tag}

المسارات (Pipelines)

النطاق المطلوب: read:pipelines أو write:pipelines

GET    /api/v1/pipelines
POST   /api/v1/pipelines
GET    /api/v1/pipelines/{id}
PUT    /api/v1/pipelines/{id}
PATCH  /api/v1/pipelines/{id}
DELETE /api/v1/pipelines/{id}

مراحل المسار

GET    /api/v1/pipelines/{pipeline_id}/stages
POST   /api/v1/pipelines/{pipeline_id}/stages
GET    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PUT    /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
PATCH  /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
DELETE /api/v1/pipelines/{pipeline_id}/stages/{stage_id}

الوسوم (Tags)

النطاق المطلوب: read:tags أو write:tags

GET    /api/v1/tags
POST   /api/v1/tags
GET    /api/v1/tags/{id}
PUT    /api/v1/tags/{id}
PATCH  /api/v1/tags/{id}
DELETE /api/v1/tags/{id}

المستخدمون (Users)

النطاق المطلوب: read:users، write:users أو delete:users

GET    /api/v1/users
POST   /api/v1/users
GET    /api/v1/users/{id}
PUT    /api/v1/users/{id}
PATCH  /api/v1/users/{id}
DELETE /api/v1/users/{id}

النماذج (Forms)

النطاق المطلوب: read:forms، write:forms أو delete:forms

GET    /api/v1/forms
POST   /api/v1/forms
GET    /api/v1/forms/{id}
PUT    /api/v1/forms/{id}
PATCH  /api/v1/forms/{id}
DELETE /api/v1/forms/{id}

تقديم نموذج

POST /api/v1/forms/{id}/submissions

الجسم: قيم حقول النموذج كأزواج مفتاح-قيمة.

الأتمتة (Automations)

النطاق المطلوب: read:automations، write:automations أو delete:automations

GET    /api/v1/automations
POST   /api/v1/automations
GET    /api/v1/automations/{id}
PUT    /api/v1/automations/{id}
PATCH  /api/v1/automations/{id}
DELETE /api/v1/automations/{id}

التكاملات (Integrations)

النطاق المطلوب: read:integrations أو write:integrations

GET    /api/v1/integrations/types
GET    /api/v1/integrations
POST   /api/v1/integrations
GET    /api/v1/integrations/{id}
PUT    /api/v1/integrations/{id}
PATCH  /api/v1/integrations/{id}
DELETE /api/v1/integrations/{id}

GET /api/v1/integrations/types يُعيد قائمة أنواع التكاملات المتاحة (Facebook، Google Ads، Mailgun، إلخ).

استقبال العملاء المحتملين الواردين

نقطة نهاية مبسّطة لإنشاء عملاء محتملين من مصادر خارجية أو webhooks أو أدوات بدون كود مثل Zapier وMake.

POST /api/inbound/leads?tenant={workspace-slug}

المصادقة باستخدام Authorization: Bearer {api_key} مع تمرير slug الـ workspace كمعامل استعلام.

جسم الطلب:

{
  "email": "[email protected]",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "phone": "+14155551234",
  "company": "Tech Corp",
  "source": "zapier",
  "notes": "Came from newsletter signup",
  "tags": ["newsletter"],
  "custom_fields": {
    "utm_campaign": "spring-promo"
  }
}

email مطلوب. جميع الحقول الأخرى اختيارية.

استجابة النجاح (201):

{
  "status": "created",
  "lead_id": 1842,
  "is_duplicate": false
}

إذا كان العميل المحتمل موجوداً مسبقاً (تطابق بالبريد الإلكتروني أو الهاتف)، يكون is_duplicate بقيمة true ويُعاد معرّف العميل الموجود.

أمثلة على الكود

cURL

curl -X GET "https://yourdomain.com/api/v1/leads?status=new&per_page=25" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Accept: application/json"

curl -X POST "https://yourdomain.com/api/v1/leads" \
  -H "Authorization: Bearer lh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Sarah","email":"[email protected]","source":"api"}'

PHP

$apiKey = 'lh_your_api_key_here';
$baseUrl = 'https://yourdomain.com/api/v1';

// List leads
$response = file_get_contents($baseUrl . '/leads', false, stream_context_create([
    'http' => [
        'header' => "Authorization: Bearer {$apiKey}\r\nAccept: application/json\r\n",
    ],
]));
$leads = json_decode($response, true);

// Create a lead
$ch = curl_init($baseUrl . '/leads');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {$apiKey}",
    "Content-Type: application/json",
    "Accept: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'first_name' => 'Sarah',
    'email'      => '[email protected]',
    'source'     => 'api',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript (fetch)

const apiKey = 'lh_your_api_key_here';
const baseUrl = 'https://yourdomain.com/api/v1';

// List leads
const response = await fetch(`${baseUrl}/leads?status=new`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Accept': 'application/json',
  },
});
const { data, meta } = await response.json();

// Create a lead
const createResponse = await fetch(`${baseUrl}/leads`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Sarah',
    email: '[email protected]',
    source: 'website',
  }),
});
const newLead = await createResponse.json();

نظرة عامة​

عنوان URL الأساسي​

المصادقة​

تحديد معدل الطلبات​

التقسيم إلى صفحات​

تنسيق الاستجابة​

استجابة ناجحة​

استجابة خطأ​

فحص الصحة​

العملاء المحتملون (Leads)​

سرد العملاء المحتملين​

الحصول على عميل محتمل​

إنشاء عميل محتمل​

تحديث عميل محتمل​

حذف عميل محتمل​

إضافة وسم إلى عميل محتمل​

إزالة وسم من عميل محتمل​

المسارات (Pipelines)​

مراحل المسار​

الوسوم (Tags)​

المستخدمون (Users)​

النماذج (Forms)​

تقديم نموذج​

الأتمتة (Automations)​

التكاملات (Integrations)​

استقبال العملاء المحتملين الواردين​

أمثلة على الكود​

cURL​

PHP​

JavaScript (fetch)​