للمطوّرين

توثيق Authevo

تحقّق من مستخدميك عبر WhatsApp باستدعاءين فقط للـ API. نقطة وصول واحدة لإرسال رمز التحقق، وأخرى للتحقق منه — دون أي حزمة SDK لتثبيتها.

مقدمة

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

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

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

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

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

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

البدء السريع

انتقل من الصفر إلى رقم هاتف مُتحقَّق منه خلال دقيقتين.

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

أنشئ حسابًا وانسخ مفتاحك السري من لوحة التحكم. تبدأ المفاتيح السرية بالبادئة sk_live_ وتُصادِق على كل طلب.

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

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

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

# 1. Send a one-time code over WhatsApp
curl -X POST https://api.authevo.dev/v1/otp/send \
  -H "Authorization: Bearer sk_live_…" \
  -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_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+201234567890", "code": "123456" }'

المصادقة

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

Authorization: Bearer sk_live_…

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

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

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

مرجع الـ API

نقطتا وصول، كلتاهما 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_live_…" \
  -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_live_…" \
  -d '{ "phone": "+201234567890", "code": "123456" }'

الاستجابة

200 OK

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

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

الأخطاء

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

422 Unprocessable Entity

{
  "error": {
    "code": "invalid_phone",
    "message": "The phone number is not a valid E.164 number."
  }
}

الحالة	الرمز	المعنى
`400`	`invalid_request`	جسم الطلب غير صحيح أو يفتقد حقلًا إلزاميًا.
`401`	`invalid_api_key`	ترويسة Authorization مفقودة أو المفتاح السري غير صالح.
`402`	`insufficient_credits`	نفد رصيد عمليات التحقق في حسابك.
`422`	`invalid_phone`	رقم الهاتف ليس رقمًا صالحًا بصيغة E.164.
`429`	`rate_limited`	طلبات كثيرة جدًا. خفِّف الوتيرة وأعِد المحاولة بعد مهلة قصيرة.

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

حدود المعدّل

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

الحدّ الأدنى للأمان

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