توثيق API إرسال رموز التحقق OTP

واجهة برمجية بسيطة لإرسال رموز التحقق عبر واتساب والـ SMS داخل العراق. طلب HTTP واحد، بدون أي مكتبة تنصبها، وتشتغل مع أي لغة برمجة. تحت راح تلگي المصادقة، أمثلة جاهزة بـ PHP و Python و cURL و Node.js، أكواد الأخطاء، وشكل الرسالة اللي توصل مستخدمك.

مهم: نص الرسالة والرمز يتولّدان من طرفنا. أنت ترسل رقم الهاتف والقناة فقط، ونحن نولّد رمزاً من 6 أرقام ونرسله بقالب ثابت، ثم تتحقق منه عبر نقطة التحقق.

المصادقة

أرسل مفتاحك بـ header اسمه Authorization مع كل طلب:

Authorization: Bearer bgs_live_xxxxxxxx

اختر لغتك

1) إرسال رمز تحقق

POST https://otp.baghdadscript.online/api/send.php

curl -X POST https://otp.baghdadscript.online/api/send.php \
  -H "Authorization: Bearer bgs_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"phone":"07701234567","channel":"whatsapp"}'

<?php
define('API_KEY',  'bgs_live_xxxxxxxx');
define('API_BASE', 'https://otp.baghdadscript.online/api');

function otp_call(string $endpoint, array $body): array {
    $ch = curl_init(API_BASE . $endpoint);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 20,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'Authorization: Bearer ' . API_KEY,
        ],
        CURLOPT_POSTFIELDS => json_encode($body),
    ]);
    $res  = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    return ['status' => $code, 'data' => json_decode($res, true)];
}

// إرسال الرمز
$r = otp_call('/send.php', [
    'phone'   => '07701234567',
    'channel' => 'whatsapp',
]);

if (!empty($r['data']['success'])) {
    // احفظه بجلسة المستخدم: تحتاجه بخطوة التحقق
    $_SESSION['otp_request_id'] = $r['data']['request_id'];
    echo "تم إرسال الرمز";
} else {
    echo "فشل: " . ($r['data']['error'] ?? 'خطأ غير معروف');
}

import requests

API_KEY  = "bgs_live_xxxxxxxx"
API_BASE = "https://otp.baghdadscript.online/api"

def otp_call(endpoint: str, body: dict) -> dict:
    res = requests.post(
        f"{API_BASE}{endpoint}",
        json=body,
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=20,
    )
    return res.json()

# إرسال الرمز
data = otp_call("/send.php", {
    "phone": "07701234567",
    "channel": "whatsapp",
})

if data.get("success"):
    request_id = data["request_id"]   # احفظه بجلسة المستخدم
    print("تم إرسال الرمز، ينتهي خلال", data["expires_in"], "ثانية")
else:
    print("فشل:", data.get("error"))

const API_KEY  = 'bgs_live_xxxxxxxx';
const API_BASE = 'https://otp.baghdadscript.online/api';

async function otpCall(endpoint, body) {
    const res = await fetch(`${API_BASE}${endpoint}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${API_KEY}`,
        },
        body: JSON.stringify(body),
    });
    return res.json();
}

// إرسال الرمز
const data = await otpCall('/send.php', {
    phone: '07701234567',
    channel: 'whatsapp',
});

if (data.success) {
    req.session.otpRequestId = data.request_id;   // احفظه بالجلسة
    console.log('تم إرسال الرمز');
} else {
    console.log('فشل:', data.error);
}

الاستجابة

{
  "success": true,
  "request_id": "req_9f3a2b8c1d4e5f60",
  "status": "pending",
  "channel": "whatsapp",
  "network": null,
  "charged": 13,
  "balance_remaining": 9987,
  "expires_in": 300}

احفظ request_id بجلسة المستخدم عندك: راح تحتاجه بخطوة التحقق. الرمز نفسه ما يُرجع لك أبداً.

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

POST https://otp.baghdadscript.online/api/verify.php

لما المستخدم يكتب الرمز بتطبيقك، أرسله لنا مع request_id ونخبرك إذا صحيح.

curl -X POST https://otp.baghdadscript.online/api/verify.php \
  -H "Authorization: Bearer bgs_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"req_9f3a2b8c1d4e5f60","code":"482913"}'

<?php
// بعد ما المستخدم يكتب الرمز بالفورمة
$v = otp_call('/verify.php', [
    'request_id' => $_SESSION['otp_request_id'],
    'code'       => $_POST['code'],
]);

if (!empty($v['data']['verified'])) {
    unset($_SESSION['otp_request_id']);
    // ✅ تم التحقق: كمّل تسجيل المستخدم أو دخوله
} else {
    $left = $v['data']['attempts_remaining'] ?? 0;
    echo "الرمز غير صحيح. متبقي {$left} محاولات.";
}

# بعد ما المستخدم يكتب الرمز
result = otp_call("/verify.php", {
    "request_id": request_id,
    "code": user_typed_code,
})

if result.get("verified"):
    print("✅ تم التحقق")
else:
    print("غير صحيح، متبقي", result.get("attempts_remaining", 0), "محاولات")

// بعد ما المستخدم يكتب الرمز
const result = await otpCall('/verify.php', {
    request_id: req.session.otpRequestId,
    code: req.body.code,
});

if (result.verified) {
    delete req.session.otpRequestId;
    // ✅ تم التحقق
} else {
    console.log(`غير صحيح، متبقي ${result.attempts_remaining} محاولات`);
}

رمز صحيح

{
  "success": true,
  "verified": true,
  "phone": "07701234567"
}

رمز خاطئ

{
  "success": true,
  "verified": false,
  "error": "الرمز غير صحيح",
  "attempts_remaining": 4
}

من أي رقم تطلع الرسالة؟

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

إذا رقمك مو مربوط أو انقطع، الـ API يرجّع كود 503 بدون أي خصم من رصيدك.

الاشتراك الشهري

إذا حسابك على الاشتراك الشهري، الحقل charged يرجع 0 ويضاف للرد حقلين:

{
  "charged": 0,
  "plan": "monthly",
  "plan_expires_at": "2026-10-26 12:00:00",
  "daily_quota": 2000,
  "daily_used": 137
}

لو وصلت الحد اليومي يرجع كود 429 بدون خصم. السعر: 10,000 د.ع (≈ $7.58) لكل 30 يوم.

القنوات والأسعار

القيمة	الوصف	السعر	الحالة
whatsapp	واتساب، رسالة عربية	13	متاحة
sms	رسالة نصية إنجليزية ما تحتاج تحدد الشبكة: سيتم معرفة الشبكة تلقائياً	65 آسياسيل 77 زين وكورك	متاحة

استجابة الإرسال ترجّع حقل channel بالقيمة الفعلية المستخدمة (sms_asiacell أو sms_other) وحقل network باسم الشبكة، عشان تعرف بالضبط شنو انخصم وليش.

الأرقام اللي ما نقدر نحدد شبكتها تُرفض بكود 422 بدون خصم، استخدم الواتساب لها.

شكل الرسالة اللي توصل مستخدمك

واتساب

رمز التحقق الخاص بك هو: 482913
لا تشارك هذا الرمز مع أي شخص.

SMS

Your verification code is 482913. Do not share it with anyone.

تقدر تضيف اسم تطبيقك داخل الرسالة من صفحة إعدادات الرسالة.

أكواد الأخطاء

الكود	السبب
401	مفتاح API غير صحيح أو ملغى
402	الرصيد غير كافي
404	request_id غير موجود
410	الرمز منتهي الصلاحية أو مستخدم مسبقاً
422	رقم أو قناة غير صحيحة
429	تجاوز حد الطلبات، أو إرسال متكرر لنفس الرقم، أو محاولات تحقق كثيرة
503	رقم الواتساب حقك مو مربوط أو منقطع، أو القناة غير مفعّلة

ملاحظات

الرمز 6 أرقام وصالح 5 دقائق، ويُستخدم مرة وحدة بس.
أقصى 5 محاولات تحقق لكل رمز، بعدها لازم تطلب رمزاً جديداً.
ما تقدر ترسل لنفس الرقم مرتين خلال دقيقة وحدة.
لا تضع مفتاح الـ API بكود الواجهة (جافاسكربت بالمتصفح)، استخدمه من السيرفر فقط.
ملاحظة: خدمة الـ SMS متوفرة فقط للأرقام داخل العراق.