للمطوّرين

توثيق Authevo

تحقق من مستخدميك عبر WhatsApp، أو بأي تطبيق مصادقة عبر TOTP. نقاط وصول REST خام لكلتا الطريقتين — دون الحاجة إلى SDK (وتتوفّر أيضًا حزمة SDK رسمية لـ Node.js/TypeScript).

مقدمة

Authevo هي واجهة تحقق WhatsApp OTP و TOTP، موجَّهة لمصر ومنطقة الشرق الأوسط وشمال إفريقيا. أرسل رمزًا لمرة واحدة إلى رقم هاتف عبر WhatsApp وتحقق مما أدخله المستخدم، أو سجّل رقم هاتف لمصادقة TOTP الثنائية وتحقق من رموز أي تطبيق مصادقة — طريقتان مستقلتان، حساب واحد.

كل طلب هو استدعاء HTTPS بسيط موجَّه إلى عنوان أساسي واحد. تعود الاستجابات بصيغة JSON ضمن غلاف ثابت ومتوقَّع، فيعمل الاستدعاءان ذاتهما بأي لغة يستخدمها خادمك بالفعل.

العنوان الأساسيhttps://api.authevo.dev

نموذج الاستدعاءين

POST /v1/otp/send: أرسِل رمزًا لمرة واحدة إلى رقم هاتف.
POST /v1/otp/verify: تحقق من الرمز الذي أدخله المستخدم.

تُسلَّم الرموز عبر WhatsApp، مع Telegram كقناة احتياطية إذا تعذّر الوصول عبر WhatsApp. اربط حساب Telegram لكل مستخدم مرة واحدة فقط — خطوة بنقرة واحدة، يُفضَّل تنفيذها فور تسجيله — وبعدها يعمل كل تحويل احتياطي تلقائيًا دون أي تغيير في شيفرة التكامل لديك.

البدء السريع

ادمج تدفّق الطلبَيْن في دقيقتين. يبدأ الإرسال عبر WhatsApp بمجرّد اكتمال توثيق أعمال Meta لحسابك؛ اربط Telegram مرة واحدة لكل مستخدم (انظر أدناه) ليغطّيك في هذه الأثناء.

احصل على مفتاح API

أنشئ حسابًا وانسخ مفتاحك السري من لوحة التحكم. تبدأ المفاتيح السرية بالبادئة sk_ وتُصادِق على كل طلب. أول 50 عملية تحقق مجّانية — بعدها يلزم حدّ أدنى للرصيد قدره $2 قبل أن تتمكّن من الإرسال.

احصل على مفتاح الـ API

أرسِل رمزًا وتحقق منه

استدعِ نقطة الإرسال مع رقم هاتف، ثم نقطة التحقق مع الرمز الذي استلمه المستخدم. اختَر بيئتك:

# 1. Send a one-time code over WhatsApp
curl -X POST https://api.authevo.dev/v1/otp/send \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+201234567890" }'

# 2. Verify the code your user entered
curl -X POST https://api.authevo.dev/v1/otp/verify \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+201234567890", "code": "123456" }'

المصادقة

تعتمد Authevo مصادقة الحامل (Bearer). مرِّر مفتاحك السري في ترويسة Authorization مع كل طلب.

Authorization: Bearer sk_…

لا توجد أساليب مصادقة أخرى — لا OAuth ولا جلسات ولا تسجيل دخول. مفتاح سري صالح هو كل ما يحتاجه الطلب.

احتفظ بمفتاحك السري على الخادم

تمنح المفاتيح السرية صلاحية كاملة للإرسال والتحقق على حسابك. لا تضمّنها أبدًا في شيفرة العميل أو تطبيقات الجوال، ولا تُودِعها في نظام إدارة الإصدارات. أجرِ استدعاءات Authevo من خادمك، وبادِر بتدوير أي مفتاح فور تسرّبه.

مرجع الـ API

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

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

إرسال الرمز

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 — يُعامَل التسجيل المُعطَّل كبداية جديدة.

الأخطاء

تستخدم Authevo رموز حالة HTTP القياسية. تُغلَّف الاستجابات الناجحة ضمن كائن data، بينما تُعيد حالات الفشل كائن error يحتوي رمزًا قابلًا للقراءة آليًا ورسالة مقروءة للبشر.

400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "body/phone must match pattern \"^\\+[1-9]\\d{6,14}$\""
  }
}

الحالة	الرمز	المعنى
`400`	`VALIDATION_ERROR`	جسم الطلب غير صحيح، أو يفتقد حقلًا إلزاميًا، أو رقم الهاتف ليس رقمًا صالحًا بصيغة E.164.
`401`	`INVALID_API_KEY`	ترويسة Authorization مفقودة أو المفتاح السري غير صالح.
`402`	`INSUFFICIENT_CREDITS`	رصيد حسابك أقل من المبلغ اللازم للإرسال — أضِف رصيدًا مدفوعًا مسبقًا للمتابعة (يلزم حدّ أدنى قدره $2).
`429`	`RATE_LIMIT_EXCEEDED`	طلبات كثيرة جدًا. خفِّف الوتيرة وأعِد المحاولة بعد مهلة قصيرة.
`503`	`TELEGRAM_UNAVAILABLE`	التحويل الاحتياطي إلى Telegram غير متاح حاليًا.

اعتمد دائمًا على حالة HTTP وعلى error.code في التفرّع، لا على الرسالة — فقد تتغيّر الرسائل.

حدود المعدّل

تخضع الطلبات لتحديد المعدّل لكل حساب. عند تجاوز الحد تُجيب الواجهة بـ 429 RATE_LIMIT_EXCEEDED — تراجَع وأعِد المحاولة بعد مهلة قصيرة.

الحدّ الآمن

إضافةً إلى حدود المعدّل البسيطة، يرصد «الحدّ الآمن» أنماط إساءة الاستخدام والإنفاق المنفلت، فيكبح حركة المرور المريبة قبل أن تُكلّفك. يعمل تلقائيًا — دون أي إعداد.