التحقق برمز OTP عبر واتساب (v1)

الـ API ده بيبعت رمز لمرة واحدة لرقم على واتساب ويتحقق من الرمز اللي المستخدم بيكتبه. Otpera بيولّد الرمز ويوصّله ويطبّق مدة الصلاحية وحدود المحاولات، وبيخزّنه كـ hash بس. السيرفر بتاعك عمره ما بيشوف الرمز.

استخدمه في التسجيل والدخول، تأكيد رقم الموبايل، تأكيد الدفع، استرجاع كلمة السر، والتحقق بخطوتين.

إزاي بيشتغل

1. Your server  ── POST /verifications {to} ─────────▶ Otpera
2. Otpera       ── WhatsApp: "Your code is 482913" ──▶ User
3. User         ── types 482913 into your app ───────▶ Your server
4. Your server  ── POST /verifications/:id/check ────▶ Otpera → { valid: true }

الخطوة	النقطة	الغرض
١	POST /verifications	إنشاء عملية تحقق وإرسال الرمز
٢	POST /verifications/{id}/check	التحقق من الرمز اللي اتكتب
–	POST /verifications/{id}/resend	إرسال رمز جديد لنفس العملية
–	GET /verifications/{id}	قراءة الحالة الحالية

كل النقاط محتاجة مفتاح بصلاحية verifications:write. الرابط الأساسي: https://api.otpera.com/api/v1.

١. إنشاء عملية تحقق

POST /verifications

الحقل	النوع	مطلوب	الوصف
to	string	أيوه	رقم المستلم بصيغة E.164 (+201012345678) أو رقم مصري محلي 01012345678
purpose	string	لأ	تسمية من عندك (signup، login، checkout). الافتراضي verification
locale	"ar" | "en"	لأ	لغة رسالة واتساب. الافتراضي لغة مساحة العمل
channel	"whatsapp"	لأ	واتساب بس حاليًا

ابعت هيدر Idempotency-Key علشان لو الطلب اتكرر ما يتبعتش رمز تاني.

curl -X POST https://api.otpera.com/api/v1/verifications \
  -H "Authorization: Bearer $OTPERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b9e-1c55-4c1e-8f0a-3f7b0e7f9a21" \
  -d '{ "to": "+201012345678", "purpose": "signup", "locale": "ar" }'

الرد 201 Created

{
  "data": {
    "id": "8b0c3f8e-2f7a-4f5e-9a51-0d6c1e6b2f10",
    "recipient_e164": "+201012345678",
    "purpose": "signup",
    "channel": "whatsapp",
    "status": "pending",
    "attempts": 0,
    "max_attempts": 5,
    "send_count": 1,
    "delivery_status": "sent",
    "expires_at": "2026-11-05T10:10:00.000Z",
    "verified_at": null,
    "created_at": "2026-11-05T10:00:00.000Z"
  }
}

المستخدم بيستلم رسالة زي:

رمز التحقق الخاص بك في متجري: 482913 — صالح لمدة 10 دقائق. لا تشاركه مع أي شخص.

إنشاء عملية جديدة لنفس الرقم ونفس purpose بيلغي أي عملية قديمة لسه مستنية، فآخر رمز بس هو اللي بيشتغل.

٢. التحقق من الرمز

POST /verifications/{id}/check بجسم { "code": "482913" } (من ٤ لـ ٨ أرقام).

{ "data": { "id": "8b0c…", "valid": true, "status": "verified", "reason": null, "attemptsRemaining": 4 } }

اعتمد دايمًا على valid. لو false، الحقل reason بيقولك السبب:

reason	status	تعرض للمستخدم
incorrect_code	pending	"الرمز غلط" + عدد المحاولات الباقية
too_many_attempts	failed	"محاولات كتير، اطلب رمز جديد"
expired	expired	"الرمز انتهى، اطلب رمز جديد"
already_verified	verified	الرمز اتستخدم قبل كده
canceled	canceled	اتطلب رمز أحدث، استخدم آخر رمز

الرمز بيتحقق مرة واحدة بس حتى لو وصل طلبين في نفس اللحظة.

٣. إعادة الإرسال

POST /verifications/{id}/resend من غير body. بيبعت رمز جديد لنفس العملية ويمدّ الصلاحية.

• ٣٠ ثانية بين كل إرسال والتاني (429 مع retryAfter).
• أقصى ٥ مرات إرسال للعملية الواحدة.
• بس لو الحالة pending (غير كده 409).

الحالات

الحالة	المعنى
pending	الرمز اتبعت ومستني التحقق
verified	الرمز الصح اتكتب
expired	عدّت ١٠ دقايق من غير تحقق صحيح
failed	محاولات غلط كتير أو فشل التسليم على واتساب
canceled	اتلغت بعملية أحدث لنفس الرقم ونفس الغرض

الحدود

الحد	القيمة
صلاحية الرمز	١٠ دقايق
محاولات غلط لكل عملية	٥
مرات الإرسال لكل عملية	٥
الانتظار بين الإرسال	٣٠ ثانية
عمليات جديدة لنفس الرقم	٥ كل ١٠ دقايق
عمليات جديدة لكل مساحة عمل	٣٠٠ في الساعة

كل رمز بيوصل بيستهلك رصيد واحد من باقتك.

أفضل الممارسات

• نادِ Otpera من السيرفر بس. الواجهة بتكلّم السيرفر بتاعك، والسيرفر معاه المفتاح.
• اربط data.id بالجلسة على السيرفر، وما تعتمدش على id جاي من المتصفح لوحده.
• حط Rate limit على الـ endpoint بتاعك اللي بيطلب الرمز (لكل IP ولكل حساب).
• اعرض عدّاد ٣٠ ثانية لزرار إعادة الإرسال.
• استخدم purpose علشان تفصل بين الدخول والدفع مثلًا.