إرسال OTP عبر الـ API

ما هي واجهة Fynchat OTP API؟

واجهة برمجية بسيطة لإرسال رموز التحقق (OTP) والتحقق منها عبر واتساب الأعمال. تُرسِل الكود إلى رقم العميل، ثم تتحقّق من الكود الذي أدخله مقابل معرّف الطلب — كل ذلك عبر طلبات REST تُطلقها من خادمك.

الرابط الأساسي لكل الطلبات:

https://fynchat.com

صفحة التوثيق الكاملة متاحة داخل لوحة التحكم على المسار /settings/otp/docs، وتضمّ أمثلة كود جاهزة للنسخ بعدّة لغات. القيم الواردة في الأمثلة (رقم الهاتف، ومعرّف الطلب، وصيغة المفتاح) توضيحية — استبدلها بقيمك الحقيقية.

نقاط النهاية

المصادقة

كل طلب يحمل مفتاح الوصول في ترويسة Authorization:

Authorization: Bearer flk_otp_xxxxxxxx_yyyyyyyy

⚠️ لا تضع المفتاح في كود الواجهة الأمامية (frontend). استخدمه من خادمك فقط.

توقيع HMAC (اختياري)

إذا فعّلت الخيار require_hmac على المفتاح، يجب توقيع كل طلب. تُضاف ترويستان: X-Timestamp وX-Signature، ويُحسب التوقيع من sha256= متبوعاً بـ hash_hmac('sha256', timestamp . '.' . body, secret).

مثال بلغة PHP:

$timestamp = time();
$body = json_encode(['phone' => '+966501234567', 'purpose' => 'login']);
$signature = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, 'YOUR_HMAC_SECRET');

// أرسلهما ضمن الترويسات:
// 'X-Timestamp' => (string) $timestamp,
// 'X-Signature' => $signature,

إرسال كود (send)

أرسل طلب POST إلى /api/v1/otp/send بالحقول التالية:

مثال بالطلب:

curl -X POST https://fynchat.com/api/v1/otp/send \
  -H "Authorization: Bearer flk_otp_xxxxxxxx_yyyyyyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+966501234567",
    "purpose": "login",
    "code_length": 6,
    "language": "ar",
    "metadata": {"user_id": 123}
  }'

نموذج الاستجابة:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "phone_masked": "+966***4567",
  "expires_at": "2026-05-22T10:35:00Z"
}

احفظ request_id — ستحتاجه في خطوة التحقق.

التحقق من الكود (verify)

أرسل طلب POST إلى /api/v1/otp/verify بالحقلين:

{
  "request_id": "550e8400-...",
  "code": "123456"
}

عند النجاح تعود الاستجابة بالحقل verified مع رقم الهاتف والبيانات الإضافية:

{ "verified": true, "phone": "+966501234567", "metadata": {...} }

وعند فشل التحقق يظهر الحقل attempts_remaining (المحاولات المتبقية) والحقل error الذي يوضّح السبب.

أمثلة الكود الجاهزة

توفّر صفحة التوثيق عارض أمثلة بتبويبات تنقلك بين اللغات: cURL، وPHP، وNode.js، وPython، إضافةً إلى تبويب HMAC للتوقيع. اضغط زر نسخ لنسخ المثال المعروض إلى الحافظة.

رموز الأخطاء

الإعدادات الافتراضية

العودة للإعدادات

لضبط مفتاحك ومراجعة صفحة التوثيق كاملةً، افتح إعدادات OTP.