الانتقال إلى المحتوى الرئيسي
POST
curl

إدراج اسم علامتك التجارية في الرسالة النصية

تحمل رموز SMS اسم مرسل الرسائل النصية الخاص بتطبيقك، والذي يُضبط في Business Console، دون أي تكلفة إضافية:
123456 هو رمز التحقق الخاص بك لدى Acme Bank
لإرسال رمز واحد باسم مختلف، مرّر options.sms_sender_name (من 1 إلى 30 حرفًا: أحرف وأرقام ومسافات والرموز ’ & - ! فقط، ولا يجوز أن يتكون من أرقام فقط):
أي اسم يخرج عن هذه القواعد يُرجع 400 ولا يُرسل أي رمز. لا تحمل رموز WhatsApp علامة تجارية، لأنها تستخدم رسالة ثابتة. اربط رقم WhatsApp Business الخاص بك في Business Console لإرسالها باسم شركتك. انظر إرسال رموز WhatsApp من رقمك الخاص. انظر رسائل التحقق المُعلَّمة بالعلامة التجارية لمعرفة الاسم الذي يحمله كل رمز، وحد الاستخدام اليومي للأسماء الجديدة.

التعامل مع انقطاع مزوّد الخدمة

إذا كان مزوّد الهاتف غير متاح مؤقتًا، يُرجع هذا endpoint الرمز 502 مع رمز ثابت قابل للقراءة بالآلة:
عامل هذه الاستجابة على أنها قابلة لإعادة المحاولة. استخدم فترة انتظار قصيرة قبل إعادة المحاولة، واعرض للمستخدم رسالة بأن الخدمة غير متاحة مؤقتًا، بدلًا من أن تطلب منه تغيير رقم هاتف أو رمز صالح.

التفويضات

x-api-key
string
header
مطلوب

مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys.

الجسم

application/json
phone_number
string
مطلوب

رقم هاتف المستلم بتنسيق E.164 — يبدأ بعلامة + ورمز الدولة (مثال: +14155552671). يتم التحقق من صحة الأرقام وتوحيد تنسيقها إلى E.164؛ وتؤدي الأرقام غير القابلة للتحليل أو غير الصالحة إلى إرجاع الرمز 400 مع خطأ في الحقل phone_number.

Maximum string length: 20
مثال:

"+14155552671"

options
object

خيارات تسليم رمز لمرة واحدة. جميع الحقول اختيارية.

signals
object

إشارات اختيارية للجهاز والشبكة حول المستخدم النهائي، تُمرَّر إلى طبقة مكافحة الاحتيال لتحسين اكتشاف حركة المرور المسيئة أو الآلية. جميع الحقول اختيارية.

vendor_data
string

معرّف اختياري يتحكم فيه المتصل (معرّف المستخدم الداخلي لديك، أو بريد إلكتروني، أو UUID، وما إلى ذلك) يُحفظ في الجلسة ويُعاد في استجابة الإرسال، واستجابة فحص التطابق، وwebhook، وBusiness Console. استخدمه لربط request_id الخاص بـ Didit بسجل المستخدم لديك.

metadata
object | null

كائن JSON اختياري حرّ التنسيق يُحفظ في الجلسة ويُعاد في استجابة الإرسال، واستجابة فحص المطابقة، وwebhooks، وBusiness Console.

الاستجابة

تم تأكيد استلام الإرسال. تحقق من status: تشير Success وRetry إلى أن الرمز في طريقه للإرسال؛ بينما تعني Blocked أن طبقة مكافحة الاحتيال قد رفضت العملية وأنه قد تم إنهاء التحقق مسبقاً بحالة Declined. تمثل request_id معرف الجلسة المحفوظ (نفس المعرف عند استخدام Retry).

request_id
string<uuid>

معرّف الجلسة لعملية التحقق. يُرجع إرسال Retry نفس قيمة request_id مثل الإرسال الأصلي. يظهر هذا المعرّف في Business Console، ويتم إرجاعه مرة أخرى بواسطة طلب POST /v3/phone/check/ مكتمل، ويمكن تمريره إلى GET /v3/session/{sessionId}/decision/.

status
enum<string>

Success — تم إرسال OTP لعملية تحقق جديدة. Retry — تمت إعادة إرسال OTP لعملية التحقق المعلقة التي تم إنشاؤها بواسطة إرسال سابق. Blocked — رفضت طبقة مكافحة الاحتيال الإرسال؛ يتم إنهاء عملية التحقق فورًا كـ Declined ولا تتم فوترة أي شيء.

الخيارات المتاحة:
Success,
Retry,
Blocked
reason
string | null

سبب كون الإرسال Blocked (على سبيل المثال، repeated_attempts، أو suspicious، أو spam). ويكون null في حالتي Success وRetry.

vendor_data
string | null

نسخة مطابقة من vendor_data المخزنة في الجلسة (من الإرسال الأول).

metadata
object | null

نسخة مطابقة من metadata المخزنة في الجلسة (من الإرسال الأول).

آخر تعديل في ٧ نوفمبر ٢٠٢٦