دليل المطورين والربط
قنّاص يجد عملاء محتملين من خرائط جوجل ويدفعهم إلى نظامك مباشرة. هذه الصفحة تشرح الطرق الثلاث للربط، وما تحتاج معرفته قبل أن تكتب سطراً.
ثلاث طرق للربط
أبسط طريق: نرسل طلب JSON واحداً إلى نقطة النهاية التي تحددها لكل حدث. يعمل مع أي نظام.
متاح الآنربط أصلي ثنائي الاتجاه، بنقرة واحدة من داخل Odoo، بلا كتابة كود.
متاح الآنتحكّم كامل: اطلب بحثاً من نظامك، تابع تقدمه، واستلم النتائج.
متاح الآنيصل العملاء إلى HubSpot وZoho اليوم عبر Zapier أو Make (لا ربط مباشر بـ API الخاص بهما). والربط الأصلي لكل منهما مدرج عندنا وقادم.
Webhook
تضيف الرابط والمفتاح السري في صفحة التكاملات، فنبدأ بإرسال طلب لكل حدث. يعمل مع Zapier و Make و n8n أو نقطة نهاية تكتبها بنفسك.
الأحداث
| الحدث | متى يُرسل |
|---|---|
lead.created | عند اكتشاف عميل جديد |
lead.updated | عند تغيّر حالة عميل أو بياناته |
test | عند الضغط على “اختبار الاتصال” |
الترويسات
| الترويسة | المعنى |
|---|---|
X-Qanas-Event | نوع الحدث، نفس قيمة event في الجسم |
X-Qanas-Delivery | معرّف فريد لكل تسليم. إعادة محاولة التسليم نفسه تستخدم المعرّف نفسه، فيمكنك إسقاط المكرر. |
X-Qanas-Timestamp | وقت الإرسال بثواني يونكس |
X-Qanas-Signature-256 | التوقيع الموصى به: يغطي الطابع الزمني والجسم معاً، فلا يمكن إعادة استخدام طلب مُسجَّل لاحقاً. |
X-Qanas-Signature | التوقيع الأقدم، على الجسم وحده. محفوظ لمن بنى عليه؛ استخدم الذي قبله في الربط الجديد. |
جسم الطلب
POST https://your-endpoint.example/qanas
Content-Type: application/json
X-Qanas-Event: lead.created
X-Qanas-Delivery: 7f3c1e9a-...
X-Qanas-Timestamp: 1790000000
X-Qanas-Signature-256: sha256=...
{
"event": "lead.created",
"lead": {
"id": 10492,
"name": "...",
"mobile": "+9665...",
"phone": "+96611...",
"email": "...",
"website": "https://...",
"address": "...",
"city": "...",
"country": "...",
"country_code": "SA",
"rating": 4.6,
"review_count": 214,
"status": "new",
"notes": "",
"keywords": "...",
"project": "...",
"google_maps_url": "https://www.google.com/maps/..."
}
}
الحقول الفارغة تُرسل كنص فارغ لا كـ null. حدث lead.updated يضيف حقل changes يحمل ما تغيّر فقط.
تغيّر بيانات عميل
حدث lead.updated يرسل العميل كاملاً، ومعه حقل changes يحمل الحقول التي تغيّرت فقط، كل حقل في صورة [قبل، بعد].
{
"event": "lead.updated",
"lead": { "...": "the full lead, as above" },
"changes": { "status": ["new", "contacted"] }
}
التحقق من التوقيع
احسب HMAC-SHA256 على الطابع الزمني ثم نقطة ثم الجسم الخام، بمفتاحك السري، وقارنه بالترويسة.
import hmac, hashlib, time
MAX_AGE = 300 # seconds
def valid(secret, timestamp, raw_body, header):
if abs(time.time() - int(timestamp)) > MAX_AGE:
return False # too old to accept
expected = "sha256=" + hmac.new(
secret.encode(),
timestamp.encode() + b"." + raw_body,
hashlib.sha256,
).hexdigest()
return hmac.compare_digest(expected, header)
استخدم الجسم الخام كما وصل، لا نتيجة إعادة ترميزه: أي فرق في المسافات أو ترتيب المفاتيح يُفسد التوقيع. وارفض الطلب إذا كان الطابع الزمني قديماً جداً.
ماذا نفعل بردّك
| ردّك | ما نفعله |
|---|---|
2xx | نعدّ التسليم ناجحاً ونحفظ معرّف السجل عندك. |
400, 422 | هذا العميل بعينه مرفوض. لا نعيد المحاولة، ويظهر في صفحة التكاملات. |
409 | نعتبره تعارضاً في سجل واحد ونعيد المحاولة بمهلة متزايدة. |
| أي رد آخر، أو انقطاع | نفترض أن المشكلة عامة لا خاصة بهذا العميل، فنوقف الإرسال مؤقتاً بمهلة متزايدة ولا نُهدر محاولة. |
إعادة المحاولة والأعطال
لا شيء يُرسل من مسار الطلب. كل حدث يدخل طابوراً ويُرسله عامل واحد، واحداً تلو الآخر، فلا يتسابق دفعان على السجل نفسه.
- إذا كان نظامك غير متاح أو رفض كل شيء، نوقف الإرسال مؤقتاً بمهلة متزايدة ولا نُهدر محاولة - لا يُفقد عميل أثناء انقطاعك.
- رد 400 أو 422 يعني أن هذا العميل بعينه مرفوض، فلا نعيد المحاولة. أي رد آخر يُعاد بمهلة متزايدة.
- ما فشل نهائياً يظهر في صفحة التكاملات بزر إعادة محاولة، فلا يضيع صامتاً.
حقول العميل
هذه الحقول نفسها تُرسل في الـ Webhook وتعود من الـ API. الحقل الذي لا قيمة له يُرسل نصاً فارغاً، ما عدا التقييم وعدد المراجعات فهما null.
| الحقل | النوع | ملاحظات |
|---|---|---|
name | string | اسم المنشأة كما في خرائط جوجل |
mobile | string | جوال بصيغة E.164. وجوده أو وجود البريد هو ما يجعل العميل محسوباً. |
phone | string | هاتف ثابت، إن وُجد. وحده لا يجعل العميل محسوباً. |
email | string | يُستخرج من موقع المنشأة عند تشغيل الخيار، ويُرفض العنوان العام أو القالبي. |
website | string | الموقع كما يذكره جوجل. قد يكون صفحة تواصل اجتماعي. |
address | string | العنوان الكامل بنص واحد |
city, country | string | المدينة والدولة كما وردت في البحث |
country_code | string | رمز الدولة بحرفين، ISO 3166-1 |
rating | number / null | من 1 إلى 5، أو null إن لم يكن للمنشأة تقييم |
review_count | integer / null | عدد المراجعات، أو null |
status | string | new عند الإنشاء. يتغيّر من قنّاص أو من نظامك. |
keywords | string | الكلمة المفتاحية التي وجدت هذا العميل |
google_maps_url | string | رابط المنشأة على خرائط جوجل |
REST API
يصلح حين تريد أن يطلب نظامك بحثاً بنفسه. المصادقة برمز Bearer تحصل عليه عند الربط، ويُخزن عندنا مُشفَّراً (SHA-256) فلا يكشفه تسرّب قاعدة البيانات.
المصادقة
كل نداء يحمل رمز Bearer. الرمز يُصدر عند الربط: يفتح نظامك متصفح العميل على قنّاص، يوافق العميل، فيعود رمز استخدام واحد يبدّله خادمك برمز وصول. لا يمر سر طويل الأجل عبر المتصفح، ورمز الاستخدام الواحد صالح عشر دقائق ولمرة واحدة.
Authorization: Bearer qat_...
نحفظ الرمز مُشفَّراً بـ SHA-256، فلا يكشفه تسرّب قاعدة البيانات. لا نعرضه بعد الإصدار، فاحفظه عندك. ولإلغائه استخدم disconnect.
نقاط النهاية
| نقطة النهاية | ماذا تفعل |
|---|---|
POST /api/v1/lead-requests | تبدأ بحثاً جديداً وتعيد معرّف الطلب |
GET /api/v1/lead-requests/<id> | تقدّم البحث، والنتائج بعد انتهائه |
POST /api/v1/lead-requests/<id>/ack | تخبرنا بأي سجل صار كل عميل في نظامك |
POST /api/v1/enrich | تبحث عن منشآت عندك في خرائط جوجل وتُكمل بياناتها |
GET /api/v1/account | من المرتبط، ورصيد النقاط، والأسعار |
POST /api/v1/purchase-link | رابط لشراء نقاط بدون تسجيل دخول |
POST /api/v1/disconnect | تُلغي هذا الرمز |
طلب بحث
نداء واحد يبدأ البحث ويعود فوراً بمعرّف الطلب. البحث يعمل في الخلفية، فلا يُحجز النداء حتى ينتهي.
curl -X POST https://qanas.jawab.sa/api/v1/lead-requests \
-H "Authorization: Bearer qat_..." \
-H "Content-Type: application/json" \
-d '{
"lead_number": 50,
"keywords": ["car spare parts", "auto parts"],
"country_code": "SA",
"areas": ["Riyadh", "Jeddah"],
"find_emails": true,
"external_ref": "odoo-campaign-18"
}'
| الحقل | النوع | ملاحظات |
|---|---|---|
lead_number | integer | كم عميلاً جديداً تريد. المكرر لا يُحسب من العدد. |
keywords | string[] | قائمة نصوص لا نصاً واحداً. كل كلمة تُبحث في كل منطقة. |
country_code | string | رمز الدولة بحرفين. أو أرسل country_name بدلاً منه. |
areas | string[] | المدن أو الأحياء. إن تركتها نبحث الدولة كلها. |
find_emails | boolean | تشغيل استخراج البريد من مواقع المنشآت. البريد الذي يُوجد يُحسب. |
external_ref | string | معرّفك للطلب. إعادة إرسال الطلب بنفس المعرّف تعيد الطلب الأول ولا تشغّل بحثاً ثانياً. |
lang | string | ar أو en. يحدد لغة أسماء النتائج والرسائل. |
الرد
201 Created
{
"request": {
"id": 412,
"external_ref": "odoo-campaign-18",
"state": "running",
"lead_number": 50,
"progress": { "done": 0, "total": 0, "step": "..." },
"new_count": 0,
"credits_charged": 0,
"error": "",
"created_at": "...",
"finished_at": null
},
"balance": 1840,
"estimate": 50
}
تابع الطلب بنداء GET على معرّفه. ما دامت الحالة running فالحقل leads غير موجود؛ يظهر مع أول حالة نهائية.
state | المعنى |
|---|---|
running | البحث يعمل. تابع progress. |
done | انتهى. الحقل leads يحمل النتائج و credits_charged ما حُسب. |
cancelled | أُلغي، وما وُجد قبل الإلغاء محفوظ ومحسوب. |
error | فشل. الحقل error يشرح السبب، ولا يُحسب إلا ما وُجد. |
بعد إنشاء السجلات عندك أرسل ack بمعرّف كل سجل، فنعرف ما صار إليه كل عميل ولا ندفع له نسخة ثانية.
الحدود
| الحد | القيمة |
|---|---|
| عدد النداءات لكل عميل | 120 / دقيقة |
| أقصى عدد عملاء في الطلب الواحد | 200 |
| أقصى عدد كلمات مفتاحية | 10 |
| أقصى عدد مناطق | 10 |
| طلبات تعمل في وقت واحد | 3 |
| أقصى عدد منشآت في نداء إثراء | 50 |
الأخطاء
كل خطأ يعود بنفس الشكل: رمز ثابت تبني عليه منطقك، ورسالة بلغة الطلب للعرض، وحقول إضافية حين تنفع.
{
"error": {
"code": "insufficient_credits",
"message": "...",
"balance": 3,
"need": 50
}
}
code | HTTP | المعنى |
|---|---|---|
bad_request | 400 | حقل ناقص أو قيمة غير مقبولة. الحقل field يسمّيه. |
unauthorized | 401 | الرمز ناقص أو غير صحيح أو مُلغى. |
insufficient_credits | 402 | الرصيد لا يكفي. يعود معه balance و need. |
account_suspended | 403 | الحساب موقوف. |
not_found | 404 | لا يوجد طلب بهذا المعرّف لهذا العميل. |
rate_limited | 429 | تجاوزت عدد النداءات في الدقيقة. أعد المحاولة بعد مهلة. |
too_many_running | 429 | لديك العدد الأقصى من الطلبات العاملة. انتظر انتهاء أحدها. |
daily_limit | 429 | تجاوزت حد الإثراء اليومي. |
service_unavailable | 503 | الخدمة غير متاحة مؤقتاً. أعد المحاولة لاحقاً. |
ما الذي يُحسب عليك
لا شيء يُحجز مقدماً. تُحسب نقطة واحدة مقابل كل عميل جديد يحمل وسيلة تواصل فعلية - جوال أو بريد. المكرر مجاني، والعميل بلا وسيلة تواصل مجاني، والبحث الذي لم يجد شيئاً لا يكلّف شيئاً. الربط نفسه والـ Webhook والـ API بلا رسوم إضافية.
- نقطة واحدة لكل عميل جديد يحمل جوالاً أو بريداً.
- المكرر مجاني، والعميل بلا وسيلة تواصل مجاني، والبحث الذي لم يجد شيئاً لا يكلّف شيئاً.
- الربط نفسه والـ Webhook والـ API بلا رسوم إضافية.
كيف تبدأ
أنشئ حساباً، افتح صفحة التكاملات، واختر Webhook أو Odoo. الاختبار متاح قبل أي التزام، ومع التسجيل نقاط مجانية تكفي لتجربة الربط من طرفه إلى طرفه.