REST API · v1

وثائق API المدى الدولية

ابدأ بربط تطبيقك خلال دقائق عبر واجهات RESTful آمنة. كل الطلبات تُرسَل عبر HTTPS وتُصادَق باستخدام Bearer Token.

المصادقة

مرّر مفتاح API في ترويسة Authorization. استخدم مفاتيح sk_test_* في الاختبار و sk_live_* في الإنتاج. لا تكشف مفاتيحك في الواجهة الأمامية.

Authorization

Authorization: Bearer sk_live_***
Content-Type: application/json

إرسال OTP

POST /api/v1/otp/send

cURL

curl -X POST https://otpiraq.cloud/api/v1/otp/send \
  -H "Authorization: Bearer sk_live_***" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "9647700000000",
    "channel": "whatsapp",
    "template": "otp_default",
    "code": "123456",
    "expiry": 300
  }'

JavaScript

const res = await fetch("https://otpiraq.cloud/api/v1/otp/send", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.ALMADAA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone: "9647700000000", channel: "whatsapp" }),
});
const data = await res.json();
// { success: true, message_id: "...", status: "sent", balance: 99.97 }

التحقق من OTP

تحقق من صحة الرمز الذي أدخله المستخدم خلال مدة الصلاحية.

cURL

curl -X POST https://otpiraq.cloud/api/v1/otp/verify \
  -H "Authorization: Bearer sk_live_***" \
  -d '{ "phone": "9647700000000", "code": "123456" }'

إرسال رسالة واتساب

Body

{
  "phone": "9647700000000",
  "template": "order_update",
  "variables": ["#10293", "تم الشحن"]
}

Webhooks

سجّل رابط Callback من لوحة التحكم لاستقبال أحداث الحالة لحظياً. نرسل POST موقّعاً بترويسة X-Almadaa-Signature.

Webhook payload

{
  "event": "message.delivered",
  "message_id": "clx...",
  "status": "delivered",
  "timestamp": "2026-06-09T10:42:00.000Z"
}

أخطاء API

400	طلب غير صالح
401	مفتاح غير صحيح أو مفقود
402	الرصيد غير كافٍ / التسعير غير مفعّل
429	تجاوز حد المعدّل
500	خطأ في الخادم

Rate Limits

الحد الافتراضي 60 طلباً في الدقيقة لكل مفتاح. تُرجِع الطلبات الزائدة الرمز 429. يمكن رفع الحد للعملاء المؤسسيين.