مرجع الـ API

نقطتا وصول لتدفّق العمل الأساسي — الإرسال والتحقق — بالإضافة إلى نقطة اختيارية لربط Telegram مسبقًا، وثلاثية TOTP الخاصة بالتسجيل والتحقق والتعطيل. جميعها POST، وجميعها JSON، وجميعها تتطلب مصادقة.

تصفّح مرجع المخطط الكامل — كل نقطة نهاية ←

إرسال الرمز

POST/v1/otp/send

يُنشئ رمزًا لمرة واحدة ويُسلِّمه إلى رقم الهاتف عبر WhatsApp. تنتهي صلاحية الرمز بعد عدد الثواني المُعاد في expires_in.

المُعامِل	النوع	إلزامي	الوصف
`phone`	`string`	إلزامي	رقم هاتف المُستلِم بصيغة E.164، متضمّنًا رمز الدولة.

الطلب

cURL

curl -X POST https://api.authevo.dev/v1/otp/send \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+201234567890" }'

الاستجابة

200 OK

{
  "data": {
    "message_id": "msg_9k2m4n8x",
    "status": "sent",
    "expires_in": 300
  }
}

يُعيد الاستدعاء الناجح مُعرِّف الرسالة وحالة sent.

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

POST/v1/otp/verify

يتحقق من الرمز الذي أدخله المستخدم مقابل الرمز الذي أُرسل إلى هاتفه، ويُعيد ما إذا كان الرمز صالحًا.

المُعامِل	النوع	إلزامي	الوصف
`phone`	`string`	إلزامي	رقم الهاتف نفسه الذي أُرسل إليه الرمز، بصيغة E.164.
`code`	`string`	إلزامي	الرمز المكوَّن من 6 أرقام الذي استلمه المستخدم عبر WhatsApp.

الطلب

cURL

curl -X POST https://api.authevo.dev/v1/otp/verify \
  -H "Authorization: Bearer sk_…" \
  -d '{ "phone": "+201234567890", "code": "123456" }'

الاستجابة

200 OK

{ "data": { "verified": true } }

عند تطابق الرمز وبقائه صالحًا تكون قيمة verified مساوية لـ true، وإلا فشل الطلب مع غلاف خطأ.

ربط Telegram (اختياري)

POST/v1/otp/telegram-link

يُنشئ رابط Telegram بنقرة واحدة لرقم هاتف، بحيث يعمل التحويل الاحتياطي إلى Telegram من أول رمز يُرسَل للمستخدم — لا بعد فشل WhatsApp لأول مرة فقط. استدعِ هذه النقطة فور تسجيل المستخدم في منتجك، ثم أرسل له الرابط مرة واحدة (بريد إلكتروني، رسالة نصية، داخل التطبيق). تنتهي صلاحية الرابط خلال 15 دقيقة ويمكن استخدامه مرة واحدة فقط — استدعاء هذه النقطة مجددًا لنفس الرقم آمن تمامًا، ويصدر رابطًا جديدًا فقط.

المُعامِل	النوع	إلزامي	الوصف
`phone`	`string`	إلزامي	رقم هاتف المستلم بصيغة E.164، متضمّنًا رمز الدولة.

الطلب

cURL

curl -X POST https://api.authevo.dev/v1/otp/telegram-link \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+201234567890" }'

الاستجابة

200 OK

{
  "data": {
    "telegram_bot_url": "https://t.me/authevo_otp_bot?start=aBc123XyZ...",
    "expires_in": 900
  }
}

يُعيد الاستدعاء الناجح رابط Telegram بنقرة واحدة وعدد الثواني التي يظل صالحًا خلالها.

مصادقة ثنائية (TOTP)

طريقة تحقق ثانية ومستقلة — أي تطبيق مصادقة (Google Authenticator أو Authy أو 1Password)، دون إرسال أي رسالة أبدًا، بسعر $0.002 فقط لكل عملية تحقق. سجّل مرة واحدة، ثم تحقّق من رمز متجدد مكوَّن من 6 أرقام إلى الأبد بعد ذلك.

في وضع الاختبار، يُعيد التسجيل سرًا تجريبيًا عامًا وثابتًا — أضفه إلى أي تطبيق مصادقة للحصول على رمز اختبار حقيقي ومتجدد. على عكس بيئة اختبار OTP، رموز TOTP التجريبية ليست دائمًا 123456 — بل تتجدد كل 30 ثانية كما في الواقع. تفاصيل وضع الاختبار الكاملة ←

التسجيل

POST/v1/totp/enroll

يُصدر سرًا مشتركًا لرقم هاتف ويُعيد رمز QR جاهزًا للعرض إلى جانب رابط otpauth:// الخام والسر نفسه — اعرض رمز QR على المستخدم، أو دعه يكتب السر يدويًا.

المُعامِل	النوع	إلزامي	الوصف
`phone`	`string`	إلزامي	رقم الهاتف المراد تسجيله، بصيغة E.164.
`replace`	`boolean`	اختياري	مرّر true لاستبدال تسجيل مؤكَّد موجود بالفعل (مثلًا فقد المستخدم جهازه). التسجيل المؤكَّد الموجود مسبقًا يُعيد الحالة 409 بدلًا من استبداله بصمت.

الطلب

cURL

curl -X POST https://api.authevo.dev/v1/totp/enroll \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+201234567890" }'

الاستجابة

200 OK

{
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "otpauth_url": "otpauth://totp/Authevo:+201234567890?secret=JBSWY3DPEHPK3PXP&issuer=Authevo&algorithm=SHA1&digits=6&period=30",
    "qr_code": "data:image/png;base64,iVBORw0KGgo...",
    "already_enrolled": false
  }
}

قيمة qr_code هي رابط بيانات PNG جاهز للاستخدام مباشرة — استخدمه مباشرةً كمصدر صورة، دون الحاجة لأي مكتبة QR من جانبك. تكون قيمة already_enrolled صحيحة فقط عند وجود سر مؤكَّد سابق لهذا الرقم.

التحقق

POST/v1/totp/verify

يتحقق من رمز مكوَّن من 6 أرقام من تطبيق المصادقة الخاص بالمستخدم مقابل السر المسجَّل له.

المُعامِل	النوع	إلزامي	الوصف
`phone`	`string`	إلزامي	رقم الهاتف المسجَّل، بصيغة E.164.
`code`	`string`	إلزامي	الرمز المكوَّن من 6 أرقام المعروض حاليًا في تطبيق مصادقة المستخدم.

الطلب

cURL

curl -X POST https://api.authevo.dev/v1/totp/verify \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+201234567890", "code": "123456" }'

الاستجابة

200 OK

{
  "data": {
    "verified": true,
    "first_confirm": true
  }
}

تكون قيمة first_confirm صحيحة فقط في الاستدعاء الذي يؤكّد تسجيلًا جديدًا تمامًا — لحظة مناسبة لعرض رسالة "كل شيء جاهز" لمرة واحدة.

التعطيل

POST/v1/totp/disable

يُوقف TOTP لرقم هاتف. آمن استدعاؤه أكثر من مرة — تعطيل رقم مُعطَّل بالفعل (أو غير مسجَّل أصلًا) يُعيد disabled: true دائمًا.

المُعامِل	النوع	إلزامي	الوصف
`phone`	`string`	إلزامي	رقم الهاتف المراد تعطيله، بصيغة E.164.

الطلب

cURL

curl -X POST https://api.authevo.dev/v1/totp/disable \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+201234567890" }'

الاستجابة

200 OK

{
  "data": {
    "disabled": true
  }
}

إعادة تسجيل الرقم نفسه لاحقًا لا يتطلب replace: true — يُعامَل التسجيل المُعطَّل كبداية جديدة.