المصادقة الصوتية

المصادقة الصوتية هي أداة اتصال-للموافقة صادرة. يطلب نظامك من Wave التحقّق من شخص؛ فتتّصل Wave بذلك الرقم، وتُشغّل رسالة قصيرة ثنائية اللغة تصف ما تجري الموافقة عليه، ثم تلتقط ضغطة المفتاح وتُعيد نتيجة موثوقة قابلة للقراءة آليًا عبر webhook موقّع (وواجهة استعلام عن الحالة). هي المكافئ الصوتي لخطوة الموافقة-بالدفع / رمز OTP — عامل أمان، وليست قائمة رد صوتي. ولأن النتيجة تحكم الوصول، فهي مصمّمة لتفشل بأمان: الموافقة الصريحة وحدها تمنح الوصول، ولا يمكن لردّ آليّ / بريد صوتي أن يوافق أبدًا.

هذا مسار صادر يبدأ عبر الواجهة (Wave تتّصل بالمستخدم). وهو يختلف عن قوائم الرد الصوتي (حيث يتّصل المتصل بك). المصادقة الصوتية مُقيّدة — اطلب من جهة تواصلك في Wave تفعيلها لحسابك.

المصادقة والفئات

كل مسار ضمن /v1/voice-auth يتطلّب مفتاح إنتاج (sk_live_) مع صلاحية voice_auth:write (أو voice_auth:read للاستعلام). لا تستطيع المفاتيح التجريبية إجراء مكالمات مصادقة حقيقية.

إنشاء طلب تحقّق (challenge)

curl https://api.wave.sa/v1/voice-auth/challenges \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: 4e1a…" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+9665XXXXXXXX",
    "locale": "ar",
    "context": { "action": "login", "app_name": "Wave Secure" },
    "assurance": "standard",
    "ttl_seconds": 90,
    "retry_on_no_answer": 0,
    "metadata": { "ref": "REF-8842" }
  }'

الحقل	مطلوب	ملاحظات
`phone_number`	✅	بصيغة E.164 (`+9665…`). الرقم الذي تتّصل به Wave.
`locale`	—	`ar` (افتراضي) أو `en` — لغة الرسالة.
`context`	—	`{ action, app_name, reference }` تُدرَج في الرسالة. بلا أسرار — لا كلمة مرور/OTP/رقم بطاقة.
`assurance`	—	`standard` (اضغط 1) أو `number_match` (انظر أدناه). الافتراضي `standard`.
`ttl_seconds`	—	من 30 إلى 180، الافتراضي 90. ينتهي الطلب بعدها.
`retry_on_no_answer`	—	من 0 إلى 2، الافتراضي 0 — إعادة اتصال تلقائية عند عدم الردّ/الانشغال، ضمن مدّة الصلاحية.
`idempotency_key`	—	أرسله كترويسة `Idempotency-Key`؛ تُعيد المحاولة نفس الطلب دون مكالمة ثانية.
`metadata`	—	بيانات معتمة؛ تُعاد في الـ webhook.

تُعيد 201 معرّف الطلب و(في وضع number_match) الأرقام المطلوب عرضها:

{ "challenge_id": "9f1c…", "state": "initiated", "expires_at": "2026-09-01T12:01:30Z" }

النتيجة — الفشل الآمن

يصل الطلب إلى حالة نهائية واحدة state:

الحالة	المعنى	تمنح الوصول؟
`approved`	وافق المستخدم (ضغط 1، أو أدخل أرقام المطابقة)	✅ نعم
`declined`	رفض المستخدم (ضغط 2)	لا
`timeout`	ردّ لكن دون إدخال صالح بعد إعادة المحاولة	لا
`no_answer` / `busy` / `failed`	لم تتّصل المكالمة	لا
`machine_detected`	ردّ بريد صوتي/آلة	لا
`expired`	لا قرار قبل `expires_at`	لا

approved وdeclined فقط قراران صريحان من المستخدم. عامِل كل حالة أخرى كعدم منح وافشل بأمان. وتحقّق دائمًا من النتيجة عبر واجهة الحالة قبل اعتماد الموافقة — دفاعًا في العمق.

كشف الردّ الآلي (AMD)

قبل أي رسالة، تُصنّف Wave من ردّ على المكالمة. ردّ الآلة أو البريد الصوتي ينتهي إلى machine_detected ولا تُشغَّل رسالة الموافقة أبدًا — فلا يمكن لبريد صوتي التقاط ضغطة أو ترك موافقة. هذا مُطبَّق، وليس بأفضل جهد.

المطابقة الرقمية عالية التوكيد

للإجراءات عالية القيمة (المدفوعات، تغييرات المشرف)، اضبط assurance: "number_match". تتضمّن استجابة 201 قيمة match_digits (مثل "47") — اعرضها لمستخدمك. تطلب المكالمة حينها من المتّصل إدخال تلك الأرقام بالضبط للموافقة. أي إدخال خاطئ لا يوافق — وهذا يُبطل إرهاق المصادقة (“فقط اضغط 1”) والموافقات العرضية.

webhook النتيجة

عند بلوغ حالة نهائية ترسل Wave حدث voice_auth.completed موقّعًا إلى نقطة webhook الخاصّة بمشروعك. تحقّق من كل تسليم:

X-Wave-Signature — sha256=…، توقيع HMAC-SHA256 للمحتوى الخام بسرّ التوقيع الخاصّ بنقطتك. ارفض أي عدم تطابق.
X-Wave-Timestamp — بالثواني (unix)؛ ارفض التسليمات الأقدم من نافذتك (مثلًا 5 دقائق).
X-Wave-Event-Id — ثابت عبر إعادات الإرسال؛ استخدمه لمنع التكرار.

الـ webhook إشعار — أعد التأكيد عبر واجهة الحالة قبل المنح.

الاستعلام عن الحالة

curl https://api.wave.sa/v1/voice-auth/challenges/9f1c… \
  -H "Authorization: Bearer sk_live_…"

تُعيد الحالة الحالية state وعدد المحاولات وamd_result والطوابع الزمنية و(عند الانتهاء) القرار. مقصورة على مؤسّستك فقط.

المعرّف الفريد للطلب، حدود المعدّل، ومكافحة الإساءة

Idempotency — أرسل Idempotency-Key؛ تُعيد المحاولة بنفس المفتاح نفس الطلب ولا تُجري مكالمة ثانية.
حدود لكل رقم ولكل جهة إصدار — تحدّ Wave من عدد الطلبات لرقم واحد ولكل مفتاح، وتحجب الأرقام/البادئات المُسيئة، لمنع القصف الصوتي والاحتيال. عند تجاوز الحدّ → 429.

الأخطاء

الرمز	HTTP	متى
`VOICE_AUTH_DISABLED`	503	غير مُفعّل لهذا الحساب
`SANDBOX_KEY_NOT_ALLOWED`	400	استُخدم مفتاح تجريبي
`VALIDATION_ERROR`	400	رقم/لغة/مدّة غير صالحة، أو `context` يحوي سرًّا
`VOICE_AUTH_BLOCKED`	403	الرقم الهدف محظور
`VOICE_AUTH_RATE_LIMITED`	429	تجاوُز حدّ لكل رقم/جهة إصدار
`VOICE_AUTH_NOT_FOUND`	404	لا يوجد طلب بهذا المعرّف لمؤسّستك

البدء

الصوت

Web Callback

واتساب

المرجع

المصادقة الصوتية

المصادقة والفئات

إنشاء طلب تحقّق (challenge)

النتيجة — الفشل الآمن

كشف الردّ الآلي (AMD)

المطابقة الرقمية عالية التوكيد

webhook النتيجة

الاستعلام عن الحالة

المعرّف الفريد للطلب، حدود المعدّل، ومكافحة الإساءة

الأخطاء

​المصادقة والفئات

​إنشاء طلب تحقّق (challenge)

​النتيجة — الفشل الآمن

​كشف الردّ الآلي (AMD)

​المطابقة الرقمية عالية التوكيد

​webhook النتيجة

​الاستعلام عن الحالة

​المعرّف الفريد للطلب، حدود المعدّل، ومكافحة الإساءة

​الأخطاء

المصادقة والفئات

إنشاء طلب تحقّق (challenge)

النتيجة — الفشل الآمن

كشف الردّ الآلي (AMD)

المطابقة الرقمية عالية التوكيد

webhook النتيجة

الاستعلام عن الحالة

المعرّف الفريد للطلب، حدود المعدّل، ومكافحة الإساءة

الأخطاء