دليل ربط Udeyou OTP بلغة cURL ============================= الرابط الأساسي https://udeyou.com/api/v1 التوثيق https://udeyou.com/docs الصيغة JSON في الطلب والرد (Content-Type: application/json) المصادقة Authorization: Bearer أو X-API-Key: هذه النسخة العربية، والنسخة الإنجليزية هي المرجع الأساسي. الكود هو نفسه المعروض في https://udeyou.com/docs ومُختبر على الواجهة. 1) قبل البدء 1) أنشئ حسابًا: https://udeyou.com/register تبدأ الحسابات الجديدة تجربة مجانية لمدة شهرين: 2000 رسالة في الشهر الأول ومثلها في الشهر الثاني. 2) أنشئ مفتاح API من لوحة التحكم: https://udeyou.com/dashboard#keys يظهر المفتاح مرة واحدة فقط، فاحفظه في متغير البيئة UDEYOU_API_KEY على خادمك. 3) أنواع المفاتيح udy_test_... لا يرسل بريدًا ولا يخصم رصيدًا، ويعمل حتى برصيد صفر. يعود الرمز في الرد ضمن الحقل code مع "test_mode": true. للتطوير والاختبار الآلي. udy_live_... يرسل البريد فعليًا ويخصم رصيدًا واحدًا لكل رمز، ويُعاد الرصيد تلقائيًا إذا تعذّر الإرسال. كل مفتاح يرى رموز نوعه فقط. 4) أبقِ المفتاح على خادمك، ولا تضعه في JavaScript المتصفح أو تطبيق الجوال أو مستودع الكود. 2) المتطلبات والتشغيل bash و curl. احفظ السكربتات الثلاثة واجعلها قابلة للتنفيذ (chmod +x send.sh verify.sh balance.sh) ثم: export UDEYOU_API_KEY=udy_test_... ./send.sh user@example.com -> يطبع otp_id (والرمز مع المفتاح التجريبي) ./verify.sh otp_... 123456 -> يتحقق من الرمز ./balance.sh -> الرصيد الحالي اضبط UDEYOU_BASE_URL فقط إذا احتجت رابطًا أساسيًا مختلفًا. 3) السكربتات ----- BEGIN send.sh ----- #!/usr/bin/env bash # Send a verification code by email. # Usage: UDEYOU_API_KEY=udy_test_... ./send.sh user@example.com BASE_URL="${UDEYOU_BASE_URL:-https://udeyou.com/api/v1}" TO="${1:-user@example.com}" curl -sS --max-time 20 -X POST "$BASE_URL/otp/send" \ -H "Authorization: Bearer $UDEYOU_API_KEY" \ -H "Content-Type: application/json" \ -d '{"to": "'"$TO"'", "lang": "ar"}' echo ----- END send.sh ----- ----- BEGIN verify.sh ----- #!/usr/bin/env bash # Verify the code the user entered. # Usage: UDEYOU_API_KEY=udy_test_... ./verify.sh otp_xxxxxxxx 123456 BASE_URL="${UDEYOU_BASE_URL:-https://udeyou.com/api/v1}" curl -sS --max-time 20 -X POST "$BASE_URL/otp/verify" \ -H "Authorization: Bearer $UDEYOU_API_KEY" \ -H "Content-Type: application/json" \ -d '{"otp_id": "'"$1"'", "code": "'"$2"'"}' echo ----- END verify.sh ----- ----- BEGIN balance.sh ----- #!/usr/bin/env bash # Current credit balance for the account that owns the key. BASE_URL="${UDEYOU_BASE_URL:-https://udeyou.com/api/v1}" curl -sS --max-time 20 "$BASE_URL/balance" \ -H "Authorization: Bearer $UDEYOU_API_KEY" echo ----- END balance.sh ----- 4) طلبات من سطر واحد (استبدل otp_id والرمز بقيمك) ----- BEGIN send a code ----- curl -sS --max-time 20 -X POST https://udeyou.com/api/v1/otp/send \ -H "Authorization: Bearer $UDEYOU_API_KEY" \ -H "Content-Type: application/json" \ -d '{"to": "user@example.com", "lang": "ar"}' ----- END send a code ----- ----- BEGIN verify a code ----- curl -sS --max-time 20 -X POST https://udeyou.com/api/v1/otp/verify \ -H "Authorization: Bearer $UDEYOU_API_KEY" \ -H "Content-Type: application/json" \ -d '{"otp_id": "otp_61b7bfa182c0d13b33a9349f", "code": "716699"}' ----- END verify a code ----- ----- BEGIN balance ----- curl -sS --max-time 20 https://udeyou.com/api/v1/balance \ -H "Authorization: Bearer $UDEYOU_API_KEY" curl -sS --max-time 20 https://udeyou.com/api/v1/balance \ -H "X-API-Key: $UDEYOU_API_KEY" ----- END balance ----- ----- BEGIN health check ----- curl -sS https://udeyou.com/api/v1/health ----- END health check ----- ----- BEGIN optional fields ----- curl -sS --max-time 20 -X POST https://udeyou.com/api/v1/otp/send \ -H "Authorization: Bearer $UDEYOU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "user@example.com", "sender_name": "My Store", "lang": "en", "code_length": 8, "expires_in": 600, "subject": "Login code", "template": "Your {{sender_name}} code is {{code}}. Valid for {{minutes}} minutes.", "reply_to": "help@example.com" }' ----- END optional fields ----- ----- BEGIN Arabic template ----- curl -sS --max-time 20 -X POST https://udeyou.com/api/v1/otp/send \ -H "Authorization: Bearer $UDEYOU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "user@example.com", "sender_name": "متجر الورد", "template": "رمز الدخول إلى متجر الورد: {{code}} (صالح {{minutes}} دقائق)" }' ----- END Arabic template ----- 5) مرجع الواجهة POST /otp/send -> 201 Created to نص إلزامي بريد المستلم، حتى 190 حرفًا. sender_name نص اختياري اسم المرسل في صندوق الوارد، من 2 إلى 60 حرفًا. الافتراضي اسم حسابك. lang نص اختياري ar (الافتراضي) أو en: لغة الرسالة الافتراضية والتذييل. code_length رقم اختياري من 4 إلى 10 خانات. الافتراضي 6. expires_in رقم اختياري الصلاحية بالثواني من 60 إلى 3600. الافتراضي 300. code نص اختياري رمز تحدده بنفسك من 4 إلى 10 أحرف أو أرقام، وإلا تولّد Udeyou رمزًا رقميًا. template نص اختياري نص عادي حتى 1000 حرف ويجب أن يحتوي {{code}}، ويمكن استخدام {{sender_name}} و {{minutes}}. subject نص اختياري حتى 120 حرفًا ويقبل المتغيرات نفسها. reply_to نص اختياري بريد يستقبل ردود العميل. أرسل code_length و expires_in كأرقام في JSON، فالقيمة النصية "6" تُرفض بالخطأ 422. إرسال رمز جديد إلى البريد نفسه يُلغي الرموز السابقة. وتنتهي كل رسالة بسطر يوضح أنها أُرسلت نيابةً عن sender_name عبر Udeyou OTP. data: otp_id و to و status ("sent") و mode ("live" أو "test") و expires_in و expires_at (ISO 8601 بتوقيت UTC) و credits_remaining، ومع المفتاح التجريبي test_mode و code (تعامل مع الرمز كنص فقد يبدأ بصفر). POST /otp/verify -> 200 OK code نص إلزامي الرمز الذي أدخله العميل (4 إلى 10 أحرف أو أرقام). otp_id نص موصى به المعرّف المعاد من /otp/send. to نص بديل بريد المستلم بدل otp_id، ويُتحقق من آخر رمز أُرسل إليه. data: verified (true) و otp_id و to و verified_at. اعتمد data.to بريدًا موثّقًا. الرمز يُستخدم مرة واحدة، وينتهي بعد expires_in ثانية، ويُقفل بعد 5 محاولات خاطئة. GET /balance -> 200 OK data: company و mode و credits. GET /health -> 200 OK (دون مفتاح) {"success": true, "status": "ok"} النجاح: {"success": true, "data": {...}} الفشل: {"success": false, "error": {"code": "...", "message": "...", ...}} 6) أكواد الأخطاء (اعتمد على error.code، أما message فنص توضيحي بالإنجليزية) 400 invalid_json جسم الطلب ليس كائن JSON. 400 invalid_code الرمز خاطئ، و attempts_remaining = المحاولات المتبقية. 401 invalid_api_key المفتاح مفقود أو بصيغة خاطئة أو غير معروف أو ملغى. 402 insufficient_credits مفتاح حي والرصيد صفر. 403 account_suspended الحساب موقوف. 404 otp_not_found لا يوجد رمز مطابق لـ otp_id أو to ضمن نوع المفتاح. 404 not_found المسار غير موجود. 405 method_not_allowed طريقة HTTP غير مدعومة لهذا المسار. 409 otp_already_used الرمز استُخدم مسبقًا. 410 otp_expired انتهت الصلاحية، أو أُرسل رمز أحدث إلى البريد نفسه. 422 validation_error حقول غير صالحة (التفاصيل في error.fields عند /otp/send). 429 rate_limited أكثر من 60 طلب إرسال في الدقيقة (retry_after). 429 resend_too_soon أقل من 60 ثانية منذ آخر رمز لهذا البريد (retry_after). 429 recipient_limit 5 رموز لهذا البريد خلال الساعة الأخيرة (retry_after). 429 too_many_attempts استُنفدت المحاولات (5)، اطلب رمزًا جديدًا. 500 server_error خطأ غير متوقع في الخادم. 502 delivery_failed تعذّر تسليم البريد، وأُعيد الرصيد. 7) الحدود (لكل حساب، ويتشاركها المفتاح الحي والتجريبي) - طلبات الإرسال: 60 في الدقيقة (rate_limited و retry_after 60). - الفاصل بين رمزين للبريد نفسه: 60 ثانية (resend_too_soon و retry_after 60). - الرموز للبريد نفسه: 5 في الساعة (recipient_limit و retry_after 3600). - المحاولات الخاطئة: 5 لكل رمز (too_many_attempts، ثم اطلب رمزًا جديدًا). - صلاحية الرمز: 300 ثانية افتراضيًا، ومن 60 إلى 3600 عبر expires_in (otp_expired). طلبات الإرسال وحدها تدخل في حد الدقيقة. وقيمة retry_after هي طول النافذة بالثواني وليست الوقت المتبقي: انتظرها ثم أعد المحاولة. 8) أفضل الممارسات - احفظ المفتاح في متغير بيئة على الخادم فقط. - المفتاح التجريبي للتطوير والاختبار الآلي، والحي للإنتاج فقط. - احفظ otp_id في جلسة المستخدم على الخادم وتحقق به. - اعتمد data.to من رد التحقق، لا البريد المرسل من التطبيق. - تعامل مع الرمز كنص، فقد يبدأ بصفر. - اعرض attempts_remaining، وعطّل زر إعادة الإرسال 60 ثانية بعد كل إرسال. - اضبط مهلة لكل طلب، ولا تعرض تفاصيل أخطاء الشبكة للمستخدم. - ألغِ أي مفتاح يُشتبه في تسرّبه من لوحة التحكم ثم أنشئ مفتاحًا جديدًا. - لا تسجّل الرموز أو المفاتيح في السجلات. الدعم: https://udeyou.com/contact (أرفق otp_id وكود الخطأ إن وُجد)