جديد بطاقة عملك الرقمية من QCards مجاناً، تشاركها بلمسة NFC أو رمز QR أنشئ بطاقتك مجاناً
قنّاص منصة اختبار السوق وتوليد العملاء المحتملين

دليل المطورين والربط

قنّاص يجد عملاء محتملين من خرائط جوجل ويدفعهم إلى نظامك مباشرة. هذه الصفحة تشرح الطرق الثلاث للربط، وما تحتاج معرفته قبل أن تكتب سطراً.

ثلاث طرق للربط

Webhook

أبسط طريق: نرسل طلب JSON واحداً إلى نقطة النهاية التي تحددها لكل حدث. يعمل مع أي نظام.

متاح الآن
Odoo و Jawab

ربط أصلي ثنائي الاتجاه، بنقرة واحدة من داخل Odoo، بلا كتابة كود.

متاح الآن
REST API

تحكّم كامل: اطلب بحثاً من نظامك، تابع تقدمه، واستلم النتائج.

متاح الآن

يصل العملاء إلى 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.

الحقلالنوعملاحظات
namestringاسم المنشأة كما في خرائط جوجل
mobilestringجوال بصيغة E.164. وجوده أو وجود البريد هو ما يجعل العميل محسوباً.
phonestringهاتف ثابت، إن وُجد. وحده لا يجعل العميل محسوباً.
emailstringيُستخرج من موقع المنشأة عند تشغيل الخيار، ويُرفض العنوان العام أو القالبي.
websitestringالموقع كما يذكره جوجل. قد يكون صفحة تواصل اجتماعي.
addressstringالعنوان الكامل بنص واحد
city, countrystringالمدينة والدولة كما وردت في البحث
country_codestringرمز الدولة بحرفين، ISO 3166-1
ratingnumber / nullمن 1 إلى 5، أو null إن لم يكن للمنشأة تقييم
review_countinteger / nullعدد المراجعات، أو null
statusstringnew عند الإنشاء. يتغيّر من قنّاص أو من نظامك.
keywordsstringالكلمة المفتاحية التي وجدت هذا العميل
google_maps_urlstringرابط المنشأة على خرائط جوجل

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_numberintegerكم عميلاً جديداً تريد. المكرر لا يُحسب من العدد.
keywordsstring[]قائمة نصوص لا نصاً واحداً. كل كلمة تُبحث في كل منطقة.
country_codestringرمز الدولة بحرفين. أو أرسل country_name بدلاً منه.
areasstring[]المدن أو الأحياء. إن تركتها نبحث الدولة كلها.
find_emailsbooleanتشغيل استخراج البريد من مواقع المنشآت. البريد الذي يُوجد يُحسب.
external_refstringمعرّفك للطلب. إعادة إرسال الطلب بنفس المعرّف تعيد الطلب الأول ولا تشغّل بحثاً ثانياً.
langstringar أو 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
      }
    }
codeHTTPالمعنى
bad_request400حقل ناقص أو قيمة غير مقبولة. الحقل field يسمّيه.
unauthorized401الرمز ناقص أو غير صحيح أو مُلغى.
insufficient_credits402الرصيد لا يكفي. يعود معه balance و need.
account_suspended403الحساب موقوف.
not_found404لا يوجد طلب بهذا المعرّف لهذا العميل.
rate_limited429تجاوزت عدد النداءات في الدقيقة. أعد المحاولة بعد مهلة.
too_many_running429لديك العدد الأقصى من الطلبات العاملة. انتظر انتهاء أحدها.
daily_limit429تجاوزت حد الإثراء اليومي.
service_unavailable503الخدمة غير متاحة مؤقتاً. أعد المحاولة لاحقاً.

ما الذي يُحسب عليك

لا شيء يُحجز مقدماً. تُحسب نقطة واحدة مقابل كل عميل جديد يحمل وسيلة تواصل فعلية - جوال أو بريد. المكرر مجاني، والعميل بلا وسيلة تواصل مجاني، والبحث الذي لم يجد شيئاً لا يكلّف شيئاً. الربط نفسه والـ Webhook والـ API بلا رسوم إضافية.

  • نقطة واحدة لكل عميل جديد يحمل جوالاً أو بريداً.
  • المكرر مجاني، والعميل بلا وسيلة تواصل مجاني، والبحث الذي لم يجد شيئاً لا يكلّف شيئاً.
  • الربط نفسه والـ Webhook والـ API بلا رسوم إضافية.

كيف تبدأ

أنشئ حساباً، افتح صفحة التكاملات، واختر Webhook أو Odoo. الاختبار متاح قبل أي التزام، ومع التسجيل نقاط مجانية تكفي لتجربة الربط من طرفه إلى طرفه.