استخدام الـ API + Webhooks

ما الذي يقدّمه الـ API؟

يسمح REST API لأنظمتك الخارجية (متجر، CRM، نظامك المخصّص) بما يلي:

• إرسال رسائل WhatsApp برمجياً
• إدارة جهات الاتصال
• إنشاء وإطلاق الحملات
• استعلام عن الرسائل والمحادثات

وWebhooks تُخطر نظامك بالأحداث المهمّة لحظياً (رسالة جديدة، اكتمال حملة، إلخ).

الخطوة 1: أنشئ مفتاح API

1. انتقل إلى الإعدادات → التكاملات → مفاتيح API
2. اضغط + مفتاح جديد
3. اختر:
   • اسم وصفي: "تكامل متجر سلة" مثلاً
   • البيئة: live للإنتاج أو test للاختبار
   • الصلاحيات: اختر فقط ما تحتاجه (مبدأ أقلّ صلاحية)
4. انسخ المفتاح فوراً — لن يظهر مرة أخرى!

الخطوة 2: أرسل أول طلب

استخدم curl للاختبار السريع:

curl https://fynchat.com/api/public/v1/contacts \
  -H "Authorization: Bearer fynk_live_YOUR_KEY"

أو استخدم JavaScript SDK:

<script src="https://fynchat.com/sdk/fyntralink.js"></script>
<script>
const fl = new Fynchat({ apiKey: 'fynk_live_xxx' });
await fl.messages.sendText('+966501234567', 'مرحباً!');
</script>

الخطوة 3: استلم Webhooks

1. انتقل إلى الإعدادات → التكاملات → Webhooks
2. اضغط + Webhook جديد
3. أدخل:
   • URL: عنوان endpoint لديك (مثلاً https://yourdomain.com/wa-webhook)
   • الأحداث: اختر ما يهمّك (message.received, campaign.completed...)
4. احفظ الـ Signing Secret — ستستخدمه للتحقّق من توقيع كل webhook

الخطوة 4: تحقّق من توقيع Webhooks

كل webhook يحمل header:

X-Fynchat-Signature: t=1715251200,v1=abc123...

تحقّق منه قبل أي معالجة:

PHP

$body = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_FYNTRALINK_SIGNATURE'];
preg_match('/t=(\d+),v1=([a-f0-9]+)/', $sig, $m);
$expected = hash_hmac('sha256', $m[1].'.'.$body, $YOUR_SIGNING_SECRET);
if (!hash_equals($expected, $m[2])) { http_response_code(401); exit; }

Node.js (مع SDK)

const valid = await Fynchat.verifyWebhook(rawBody, sigHeader, secret);
if (!valid) return res.status(401).send('Invalid signature');

نصائح

• استخدم Test API key أثناء التطوير
• تحقّق من التوقيع دائماً — لا تثق بأي webhook دون التحقّق منه
• أعد 200 OK بسرعة (أقل من 10 ثوانٍ). عالج المنطق في job/queue
• اعتمد Idempotency: X-Fynchat-Delivery هو ID فريد لكل webhook، فتجاهل المكرّرات
• انتبه إلى حدّ 100 طلب/دقيقة — هذا الحدّ لكل مفتاح

راجع التوثيق الكامل

https://fynchat.com/api/docs — مرجع شامل لكل endpoint مع أمثلة.