انتقل إلى المحتوى
WbizTool

أدلة المنتج

مفاتيح API وClient ID

يتيح مفتاح API لبرامجك الخاصة، ولأدوات مثل Zapier وn8n وMake وإضافة WordPress، إرسال رسائل WhatsApp من أرقام مساحة عملك. ترسل شيفرتك الخاصة المفتاح في ترويسة Authorization: Bearer؛ أما التكاملات فتطلب قيمتين من صفحة مفاتيح API: ‏Client ID الخاص بمساحة عملك، وأحد مفاتيحها. وفي الصفحة نفسها السرّ الذي نوقّع به webhooks.

من يمكنه ذلك: المالكون فقط – كل مالك في مساحة العمل، لا منشئها وحده. يرى المالكون كل مفاتيح مساحة العمل وينشئونها وينسخونها ويحذفونها، أيًّا كان من أنشأها. لا يرى المحررون والمحللون مفاتيح API في الشريط الجانبي ولا في صفحة الإعدادات، ويفتح لهم أي رابط إليها تبويب الملف الشخصي (راجع الأدوار والصلاحيات). تعمل المفاتيح في كل الباقات، بما فيها الفترة التجريبية المجانية؛ وما ترسله بها يستهلك رسائل مساحة العمل.

افتح مفاتيح API ضمن التكاملات في الشريط الجانبي، أو انتقل إلى الإعدادات ← مفاتيح API.

تبويب “مفاتيح API” في الإعدادات: Client ID ‏5012 مع زر “نسخ”، والمفتاحان “موقع المتجر” و“ربط Zapier” مع تاريخ إنشاء كل منهما، وآخر أربعة أحرف من كل مفتاح، و“نسخ المفتاح” و“حذف”، وزر “إنشاء مفتاح” محاطًا بإطار (1)

يعرض كل مفتاح اسمه، وتاريخ إنشائه (أُنشئ في …)، وآخر أربعة أحرف منه (مثل •••• 7f3a)، ونسخ المفتاح وحذف. يظهر أحدث مفتاح أولًا.

إنشاء مفتاح API#

  1. انقر على إنشاء مفتاح

    في الإعدادات ← مفاتيح API، انقر على إنشاء مفتاح أعلى البطاقة على اليسار.

  2. سمِّه (اختياري)

    تحت الاسم (اختياري)، اكتب اسم التطبيق الذي سيستخدمه، مثل n8n أو Website (حتى 50 حرفًا). إذا تركته فارغًا، فسيحصل على اسم مثل "API Key 3"، كما يوضح التلميح تحت الحقل.

  3. أنشئه

    انقر على إنشاء مفتاح.

    مربع الحوار “إنشاء مفتاح API”: n8n مكتوبًا تحت “الاسم (اختياري)” (2)، والتلميح حول الاسم الافتراضي، وزر “إنشاء مفتاح” محاطًا بإطار (3)
  4. انسخ المفتاح

    يعرض مفتاح API الجديد المفتاح كاملًا: «انسخه الآن – لن ترى المفتاح كاملًا مرة أخرى. لاحقًا، يقوم "نسخ المفتاح" بنسخه دون إظهاره.» انقر على نسخ ("تم نسخ المفتاح.")، والصق المفتاح في تطبيقك أو تكاملك، ثم انقر على تم.

    مربع الحوار “مفتاح API الجديد”: الاسم n8n، والمفتاح كاملًا مع زر “نسخ” محاطًا بإطار (4)، والملاحظة الصفراء “انسخه الآن – لن ترى المفتاح كاملًا مرة أخرى”، و“تم”
  • حتى 10 مفاتيح لكل مساحة عمل. عند وجود 10، يصبح إنشاء مفتاح رماديًا، وتظهر عند الإشارة إليه الرسالة "يمكن أن يكون لديك حتى 10 مفاتيح API. احذف مفتاحًا لإنشاء آخر."
  • لا تنتهي صلاحية المفاتيح، ولا يمكن إعادة تسميتها أو إيقافها: يعمل المفتاح إلى أن يُحذف.
  • مفتاح واحد لكل تطبيق. سمِّ كل مفتاح باسم التطبيق الذي يستخدمه، لتتمكن من استبدال أحدها أو حذفه دون تعطيل الباقي.
  • أي مساحة عمل: ينتمي المفتاح إلى مساحة العمل التي كانت محددة عند إنشائه، وكل طلب يُرسَل به يعمل على تلك المساحة: أرقامها ورسائلها وباقتها. للإرسال من مساحة عمل أخرى، انتقل إليها وأنشئ مفتاحًا هناك.

ما تُدخله في تطبيقك#

حقل APIالاسم في التكاملاتأين تجده
client_idClient IDسطر Client ID أعلى بطاقة مفاتيح API. ينسخه زر نسخ المجاور له ("تم نسخ Client ID."). وهو نفسه لكل المفاتيح في مساحة العمل.
api_keyAPI keyالمفتاح الذي نسخته: 40 حرفًا من الأرقام والحروف من a إلى f.
whatsapp_clientWhatsApp Client IDمعرّف الرقم، مثل المعرّف 101 ⧉ على بطاقته في أرقام WhatsApp: انقر عليه لنسخه، أو اعرض كل الأرقام عبر API عرض حسابات WhatsApp. وهو يحدد الرقم الذي يُرسل. راجع صفحة أرقام WhatsApp.

أين تُدخلها:

  • شيفرتك الخاصة: في ترويسة Authorization: Bearer YOUR_API_KEY في كل طلب (موصى به). يحدّد المفتاح مساحة عمله، لذا يمكن حذف client_id؛ وإذا أرسلته، فيجب أن يظل Client ID الخاص بهذه المساحة. راجع إرسال المفتاح في ترويسة، وإرسال رسالة لأول رسالة بلغات cURL وPython وNode.js وPHP.
  • Zapier: ‏Client ID ومفتاح API عند ربط حسابك.
  • n8n: الحقول Client ID وAPI Key وWhatsApp Client ID في بيانات اعتماد WbizTool.
  • Make وPabbly Connect وأدوات أخرى: جسم طلب HTTP.
  • WordPress: ‏WbizTool → Settings، تحت API Configuration.

يُعَدّ Google Sheets وShopify في لوحة التحكم، ولا يحتاجان إلى مفتاح.

إرسال المفتاح في ترويسة#

تأخذ كل نقطة نهاية /api/v1/ المفتاح في ترويسة Authorization، كما سيفعل الإصدار القادم API v2:

Authorization: Bearer YOUR_API_KEY
  • client_id اختياري مع الترويسة: المفتاح هو الذي يحدّد مساحة العمل. إذا أرسلت client_id أيضًا، فيجب أن يكون Client ID الخاص بهذه المساحة، كما كان من قبل.
  • أرسل المفتاح في مكان واحد. مع الترويسة، اترك api_key خارج الجسم، أو أرسل المفتاح نفسه. إذا اختلفا، يُستخدم مفتاح الترويسة عندما يكون مفتاحًا صالحًا؛ وإذا كانت الترويسة تحمل شيئًا آخر (رمز أداة أخرى مثلًا)، يُستخدم api_key الموجود في الجسم.
  • المفاتيح في الجسم لا تزال تعمل (client_id وapi_key بصيغة JSON أو كحقول نموذج)، فلا يتغير شيء للتطبيقات والتكاملات التي ترسلها بهذه الطريقة. الترويسة أفضل، لأن أجسام الطلبات تنتهي في السجلات والوكلاء (proxies) وسجلات أدوات بناء النماذج أكثر من الترويسات.
  • تعمل حقول النماذج وعمليات الرفع multipart وأجسام JSON كلها مع الترويسة.
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "phone": "919876543210", "msg": "Hello from WbizTool"}'

اختبار مفتاحك#

استدعِ التحقق من بيانات الاعتماد (POST /api/v1/me/) مع مفتاحك، وwhatsapp_client إن أردت. تعني "status": 1 مع "message": "Okay" أنها تعمل معًا. لا يرسل هذا الطلب شيئًا ولا يستهلك رسائل، لكنه لا يتحقق من أن لديك رسائل متبقية أو من أن الرقم متصل.

curl -X POST https://wbiztool.com/api/v1/me/ -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{"whatsapp_client": 101}'

يُجيب المفتاح العامل بـ {"status": 1, "message": "Okay", "name": "…"}.

نسخ مفتاح مرة أخرى#

انقر على نسخ المفتاح بجانب المفتاح. يُنسخ المفتاح كاملًا إلى الحافظة دون أن يظهر في الصفحة؛ وترى مثلًا «تم نسخ "ربط Zapier".»، ويعرض الزر تم النسخ ✓ للحظة. لا تحتاج إلى مفتاح جديد لأنك فقدت القديم.

لمعرفة المفتاح الذي يستخدمه تطبيق ما، قارن آخر أربعة أحرف من مفتاحه بالقائمة.

حذف مفتاح#

  1. انقر على حذف

    انقر على حذف بجانب المفتاح.

  2. أكّد

    يحذّر مربع الحوار «حذف "…"؟»: "سيتوقف كل ما يستخدم هذا المفتاح عن العمل فورًا: Zaps في Zapier، وسيناريوهات n8n وMake، وإضافة WordPress، واستدعاءات API الخاصة بك. امنحها مفتاحًا آخر أولًا. لا يمكن التراجع عن ذلك." انقر على حذف المفتاح. تظهر الرسالة «تم حذف "…".»

من تلك اللحظة، تحصل الطلبات بذلك المفتاح على Auth Error: invalid api key. ويبقى ما فعله من قبل: الرسائل التي وضعها في قائمة الانتظار تظل تُرسَل (ألغِها في التقارير إذا لزم الأمر)، والتذكيرات التي أنشأها تستمر في العمل. ويستمر مشغّل Zapier ‏Incoming WhatsApp Message المُعَدّ به أيضًا في تلقي الرسائل، لأن webhook الخاص به موجود بالفعل على الرقم: أوقف الـ Zap في Zapier لإيقافه.

استبدال مفتاح#

استبدل المفتاح عندما يُحتمل أنه تسرّب، أو عندما يغادر شخص كان بإمكانه نسخه، أو من حين لآخر. لا يوجد زر للتدوير: أنشئ المفتاح الجديد أولًا، حتى لا يتوقف شيء في الأثناء.

  1. أنشئ مفتاحًا جديدًا

    أنشئ مفتاحًا وانسخه. إذا كان لديك 10 مفاتيح، فاحذف أولًا مفتاحًا لم تعد تستخدمه.

  2. حدّث تطبيقاتك

    الصق المفتاح الجديد في كل تطبيق وتكامل كان يستخدم المفتاح القديم، وتحقّق من كل منها، مثلًا عبر التحقق من بيانات الاعتماد.

  3. احذف المفتاح القديم

    احذفه. يتوقف عن العمل فورًا.

  4. تحقّق من إساءة الاستخدام (بعد التسرّب)

    ابحث في التقارير عن رسائل لم ترسلها، وألغِ ما لا يزال منها منتظرًا. في التذكيرات، احذف التذكيرات التي لم تنشئها، لأنها تستمر في العمل. أزل الأرقام التي لم تضفها في أرقام WhatsApp. ومع إضافة Unibox، ابحث في أرقام صندوق الوارد عن شارة Zapier أو webhook لا تعرفه.

الحفاظ على أمان مفاتيحك#

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

  • احتفظ بالمفاتيح على خادمك، في متغير بيئة أو في مخزن بيانات الاعتماد الخاص بتكاملك. لا تضع مفتاحًا أبدًا في JavaScript لموقع ويب، أو في تطبيق جوال، أو في جدول بيانات مشترك، أو في شيفرة تنشرها.
  • لا ترسل المفاتيح عبر البريد الإلكتروني أو الدردشة. الصقها مباشرة في التطبيق الذي يحتاج إليها.
  • استخدم مفتاحًا واحدًا لكل تطبيق، واحذف المفاتيح التي لم تعد تستخدمها.
  • استبدل المفاتيح من حين لآخر، وفورًا إذا كان يُحتمل أن أحدها تسرّب.

‏Client ID وحده ليس سرًّا، لكن تعامل مع كل مفتاح كما تتعامل مع كلمة مرور.

مفاتيح API v2#

لـAPI v2 مفاتيحه الخاصة، وتُنشأ في بطاقة مفاتيح API v2 في التبويب نفسه. وهي أكثر أمانًا من المفاتيح السابقة:

  • تُعرض مرة واحدة. لا يُعرض المفتاح كاملًا (wbz_live_…) إلا عند إنشائه؛ ولا يحتفظ WbizTool إلا ببصمة له. إذا فقدته، فألغِه وأنشئ مفتاحًا جديدًا.
  • ما يحتاج إليه فقط. حدّد ما يمكن للمفتاح فعله (إرسال الرسائل، وقراءة الرسائل، والتذكيرات، والأرقام، والوسائط، وفحص الأرقام)، وقيّده ببعض أرقامك، وامنحه تاريخ انتهاء إن شئت.
  • مفاتيح الاختبار. يفحص مفتاح الاختبار (wbz_test_…) كل طلب كما يفعل المفتاح المباشر، لكنه لا يرسل شيئًا – لبناء تكامل وتجربته.
  • آخر استخدام. يعرض كل مفتاح متى استُخدم آخر مرة ومن أين. يوقف إبطال المفتاح فورًا، ومعه نقاط استقبال webhook التي أنشأها.

تعمل المفاتيح السابقة مع API v1 فقط، وتعمل مفاتيح API v2 مع v2 فقط. راجع الانتقال من v1 إلى v2.

توقيعات webhook#

يوقّع WbizTool كل webhook يرسله إليك، لتتمكن نقطة النهاية لديك من التحقق من أن الطلب جاء منا فعلًا ولم يُغيَّر في الطريق: webhook حالة الرسالة (أُرسلت، فشلت، أُلغيت، انتهت صلاحيتها)، وأحداث ربط الأرقام، وwebhooks صندوق الوارد. تبقى الأجسام كما كانت؛ وتُضاف ترويستان:

الترويسةالقيمة
WbizTool-Timestampوقت الإرسال، بثواني Unix، مثل 1792310400
WbizTool-Signature‏v1=‎ متبوعًا بقيمة HMAC-SHA256 الست عشرية لـ <timestamp>.<raw body>، محسوبةً بسرّ التوقيع الخاص بمساحة عملك

يغطي التوقيع البايتات نفسها التي نرسلها تمامًا: حقول النموذج كما تصل، والجسم الكامل بصيغة multipart عند إرفاق صورة رمز QR، وJSON الخاص بـ webhooks صندوق الوارد. وتستمر المستقبِلات التي تتجاهل الترويستين في العمل.

الحصول على سرّ التوقيع#

في الإعدادات ← مفاتيح API، تعرض بطاقة سرّ توقيع webhook تحت مفاتيحك آخر أربعة أحرف من السرّ، مثل •••• b70d. لكل مساحة عمل سرّ واحد لكل webhooks الخاصة بها؛ ويُنشأ مع أول webhook نرسله إليك.

  1. انقر على إظهار سرّ جديد

    انقر على إظهار سرّ جديد (أو إنشاء سرّ إذا لم يكن لمساحة العمل سرّ بعد). يحذّر مربع الحوار "استبدال سرّ التوقيع؟" من أن السرّ الحالي يتوقف عن العمل فورًا. انقر على إنشاء سرّ جديد.

  2. انسخه

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

لا يرى البطاقة إلا المالكون. إنشاء سرّ جديد يستبدل القديم فورًا، لذا حدّث مستقبِلاتك مباشرة بعد ذلك؛ فالـ webhooks التي تُرسَل في الأثناء تفشل في تحققك.

التحقق من webhook#

احسب التوقيع من الجسم الخام (قبل أن يحلّله إطار العمل لديك)، وقارنه بالترويسة بمقارنة ثابتة الزمن، وارفض الطوابع الزمنية الأقدم من 5 دقائق، حتى لا يمكن إعادة تشغيل طلب قديم:

import hashlib, hmac, time

def verify(secret: str, body: bytes, headers) -> bool:
    ts, sig = headers["WbizTool-Timestamp"], headers["WbizTool-Signature"]
    mac = "v1=" + hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(ts)) < 300 and hmac.compare_digest(mac, sig)

في Django مرّر request.body وrequest.headers؛ وفي Flask ‏request.get_data() وrequest.headers.

أجب بـ 2xx عندما ينجح التحقق، وبـ 401 عندما يفشل. وتظل webhooks صندوق الوارد التي لها مفتاح سري خاص بها (المفتاح السري لـ webhook الخاص بالرقم) تحمل X-Wbiztool-Signature أيضًا؛ أما WbizTool-Signature فهو المخطط نفسه على كل webhook.

استكشاف الأخطاء وإصلاحها#

الرسالة أو المشكلةما يجب فعله
لا تظهر مفاتيح API في الشريط الجانبي ولا في صفحة الإعداداتأنت محرر أو محلل في مساحة العمل هذه. اطلب من مالك مفتاحًا، أو أن يمنحك دور مالك.
إنشاء مفتاح رماديلدى مساحة العمل 10 مفاتيح. احذف مفتاحًا لم تعد تستخدمه.
"تعذّر النسخ – منع متصفحك الوصول إلى الحافظة. حاول مرة أخرى."اسمح لموقع wbiztool.com بالوصول إلى الحافظة في متصفحك، أو جرّب متصفحًا آخر. في مفتاح API الجديد يمكنك أيضًا تحديد المفتاح ونسخه بنفسك.
"تعذّر الحصول على المفتاح. حاول مرة أخرى."أعد تحميل الصفحة وانقر على نسخ المفتاح مرة أخرى.
"تم حذف هذا المفتاح بالفعل."حذفه مالك آخر في الأثناء. تعرض القائمة المفاتيح المتبقية.
يظهر مفتاح بالحالة غير نشطلا يعمل. احذفه وأنشئ مفتاحًا جديدًا.
Auth Error: invalid api keyحُذف المفتاح أو كُتب خطأً (انسخه مرة أخرى، دون مسافات)، أو أن client_id ليس Client ID الخاص بمساحة العمل هذه.
Auth Error - Please send correct API key and Client id‏api_key مفقود أو فارغ.
يفشل webhook في التحقق من التوقيع لديكتحقّق مقابل الجسم الخام، لا مقابل حقول محلَّلة ثم أُعيد ترميزها؛ واستخدم السرّ الحالي (بعد إظهار سرّ جديد لا يعمل إلا الجديد)؛ وتحقّق من ساعة خادمك (يُرفض الطابع الزمني الذي يختلف بأكثر من 5 دقائق).
Auth Error‏client_id أو api_key مفقود، أو أن الجسم ليس JSON ولا حقول نموذج، أو أن الطلب ليس POST، في نقاط نهاية مثل الإرسال إلى عدة أرقام وجدولة رسالة وحالة الرسالة.
Invalid client id. أو Invalid Client Id أو client_id is required أو client_id must be a valid integer‏client_id مفقود أو ليس عددًا مثل 5012. انسخه من سطر Client ID.
Invalid WhatsApp Client ID (التحقق من بيانات الاعتماد) أو Invalid whatsapp client … (إرسال رسالة)معرّف الرقم ليس في مساحة عمل هذا المفتاح، أو أُزيل الرقم. انسخ المعرّف … ⧉ من أرقام WhatsApp.
البريد الإلكتروني "لا رسائل من … منذ يومين"ترسل مساحة عملك عادةً عبر API أو تكامل كل يوم، ولم يصل شيء منذ يومين. يذكر البريد أي مفتاح أُنشئ أو حُذف خلال الأسبوع الماضي: تحقّق من أن التطبيق لا يزال لديه مفتاح يعمل (راجع الإشعارات).
Invalid API key أو Invalid client_id for this API keyواجهات API للتحقق من الأرقام أو للوسائط: المفتاح خاطئ أو محذوف، أو أن client_id لا ينتمي إلى مساحة عمل المفتاح.
This API key is not linked to a workspace. Create a new API key in WbizTool.المفتاح من إعداد حساب قديم. أنشئ مفتاحًا جديدًا واستخدمه بدلًا منه.
Only workspace owners and editors can connect Zapier triggersأنشأ المفتاحَ شخصٌ لم يعد مالكًا أو محررًا. أنشئ مفتاحًا جديدًا وأعد ربط Zapier.
Demo Account can not access apisلا يمكن للحساب التجريبي استخدام API. سجّل للحصول على حسابك الخاص.
Not enough creditsالمفتاح يعمل، لكن مساحة العمل على الباقة المجانية ولم تتبقَّ لها رسائل. راجع الباقات والفوترة.
الطلبات تعمل على مساحة العمل الخطأأُنشئ المفتاح في مساحة عمل أخرى. انتقل إلى مساحة العمل الصحيحة وأنشئ مفتاحًا هناك.

صفحات ذات صلة#