مرجع الـ API

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

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

المُوصى به: اربط Telegram قبل إرسال أي رمز على الإطلاق

لا يمكن دفع رسالة عبر Telegram كما في WhatsApp — يجب على المستلم فتح رابط والنقر على Start مرة واحدة قبل أن تتمكن Authevo من مراسلته هناك. افعل ذلك لحظة تسجيله، لا لحظة فشل WhatsApp: تصبح خطوة إعداد هادئة بدلًا من مقاطعة أثناء التحقق، ومن حينها يعمل التحويل الاحتياطي بصمت في الخلفية — دون رابط أو نقرة أو أي شيء يلاحظه مستخدمك. اطّلع على قسم ربط Telegram أدناه

إرسال الرمز

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": 600
  }
}

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

التعامل مع التحويل الاحتياطي إلى Telegram

إذا تعذّر الوصول إلى هذا المستلم عبر WhatsApp ولم يربط Telegram بعد، يُعيد /send الخطأ 409 CHANNEL_NOT_LINKED بدلًا من 200 المعتادة — اعرض له error.telegram_bot_url (رابط، رمز QR، أي واجهة تناسبك). بمجرد أن ينقر Start في Telegram، تُسلِّم Authevo رمزًا جديدًا هناك تلقائيًا — لا حاجة أبدًا لإعادة استدعاء /send أو الاستعلام عن أي شيء. تفضّل تجنّب هذه الرحلة الإضافية من الأساس؟ استدعِ نقطة ربط Telegram أدناه بشكل استباقي فور التسجيل، بحيث يكون التحويل الاحتياطي مربوطًا بالفعل قبل الحاجة إليه.

409 CHANNEL_NOT_LINKED

{
  "error": {
    "code": "CHANNEL_NOT_LINKED",
    "message": "Could not deliver via WhatsApp, and this recipient has not linked the Telegram fallback. Ask them to open the link below in Telegram and tap Start — no typing required.",
    "telegram_bot_url": "https://t.me/authevo_otp_bot?start=aBc123XyZ..."
  }
}

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

# If WhatsApp can't reach this recipient and they haven't linked the
# Telegram fallback yet, you get a 409 instead of the usual 200:
#
#   {
#     "error": {
#       "code": "CHANNEL_NOT_LINKED",
#       "message": "...",
#       "telegram_bot_url": "https://t.me/authevo_otp_bot?start=..."
#     }
#   }
#
# Show error.telegram_bot_url to this recipient. Once they tap Start in
# Telegram, Authevo delivers a fresh code there automatically — no need to
# retry /send or poll for anything.

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

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 دقيقة ويمكن استخدامه مرة واحدة فقط — استدعاء هذه النقطة مجددًا لنفس الرقم آمن تمامًا، ويصدر رابطًا جديدًا فقط.

افعل ذلك مرة واحدة، مبكرًا، ولن يرى معظم مستخدميك أي طلب ربط بـ Telegram على الإطلاق — أي فشل لاحق في WhatsApp سيُحلّ بصمت عبر محادثة Telegram المربوطة بالفعل.

المُعامِل	النوع	إلزامي	الوصف
`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 — يُعامَل التسجيل المُعطَّل كبداية جديدة.