توثيق واجهة API

المصادقة والقواعد العامة

• أرسل مفتاح API في المتغير key؛ يرى كل مستخدم مفتاحه في لوحة المستخدم ← الإعدادات ← بطاقة «API الموزّعين» ويمكنه إعادة توليده.
• تُرسل جميع الطلبات بطريقة POST وتكون الاستجابة دائماً JSON؛ حتى الأخطاء تُعاد برمز الحالة 200.
• يجب أن يكون الحساب مفعّلاً، وإلا كانت الاستجابة {"error":"Your account is not active"}.
• إذا تم إيقاف API من إعدادات الإدارة تكون الاستجابة {"error":"API is disabled by administrator"}.

فهرس الأوامر

action=balance الحصول على الرصيد

الحصول على رصيد المحفظة وعملة الحساب

المعاملات

مثال الاستجابة

{
  "balance": "100.84292",
  "currency": "Toman"
}

action=services قائمة الخدمات

جلب القائمة الكاملة للخدمات المفعّلة مع المعرف والتصنيف والسعر وحدود الكمية

المعاملات

مثال الاستجابة

[
  {
    "service": 1,
    "name": "Instagram Followers - Real",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.90",
    "min": "100",
    "max": "10000"
  },
  {
    "service": 2,
    "name": "Instagram Likes - Quick",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.12",
    "min": "50",
    "max": "50000"
  }
]

action=add تقديم طلب جديد

تقديم طلب جديد؛ يُخصم المبلغ من المحفظة تلقائياً

المعاملات

مثال الاستجابة

{
  "order": 23501
}

action=status حالة الطلب

متابعة حالة الطلب والمبلغ والعدّاد الابتدائي والمتبقي

المعاملات

مثال الاستجابة

{
  "charge": "0.27819",
  "start_count": "3572",
  "status": "Partial",
  "remains": "157",
  "currency": "Toman"
}

action=cancel طلب إلغاء الطلب

تسجيل طلب إلغاء الطلب ويُطبّق بعد مراجعة الإدارة. السبب اختياري ويُعرض في لوحة الإدارة.

المعاملات

مثال الاستجابة

{
  "order": 23501,
  "cancel": "Pending"
}

action=refill طلب إعادة التعبئة

تسجيل طلب إعادة تعبئة للطلبات المكتملة أو الجزئية التي أُرسلت إلى المزوّد.

المعاملات

مثال الاستجابة

{
  "order": 23501,
  "refill": "Pending"
}

action=ai_balance رصيد توكن الذكاء الاصطناعي

الحصول على رصيد التوكن واسم النموذج المعروض وسعر التوكن (عدد التوكن مقابل المبلغ الأساسي).

المعاملات

مثال الاستجابة

{
  "tokens": "250000",
  "model": "gpt-4o-mini",
  "model_label": "Neuro AI",
  "rate_amount": "10000",
  "rate_tokens": "83333",
  "currency": "Toman"
}

action=ai_chat محادثة مع نموذج الذكاء الاصطناعي

إرسال رسالة إلى النموذج المتصل باللوحة؛ يُخصم التوكن المستهلك تلقائياً من الرصيد ويُسجّل في تقرير الاستهلاك.

المعاملات

مثال الاستجابة

{
  "reply": "Hello! How can I help you today?",
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 48,
    "total_tokens": 80
  },
  "tokens": "249920"
}

action=ai_packages حزم التوكن

جلب حزم التوكن المفعّلة مع عدد التوكن ومبلغ الشحن لكل حزمة.

المعاملات

مثال الاستجابة

[
  {
    "package": 1,
    "name": "Basic",
    "tokens": "100000",
    "price": "12000.00",
    "currency": "Toman"
  },
  {
    "package": 2,
    "name": "Pro",
    "tokens": "500000",
    "price": "55000.00",
    "currency": "Toman"
  }
]

action=ai_buy_package شراء حزمة توكن

شراء حزمة توكن من رصيد المحفظة؛ تُضاف التوكن المشتراة فوراً.

المعاملات

مثال الاستجابة

{
  "package": 1,
  "name": "Basic",
  "tokens": "100000",
  "balance": "100000"
}

action=ai_usage تقرير استهلاك التوكن

إحصاءات استهلاك التوكن: الرصيد وعدد الطلبات ومجموع الإدخال/الإخراج/الكل وآخر الطلبات.

المعاملات

مثال الاستجابة

{
  "tokens": "249920",
  "requests": "12",
  "prompt": "820",
  "completion": "1180",
  "total": "2000",
  "avg": "167",
  "items": [
    {
      "prompt_tokens": "32",
      "completion_tokens": "48",
      "total_tokens": "80",
      "model": "Neuro AI",
      "created_at": 1763892000,
      "date": "2026-09-22 14:05"
    }
  ]
}

action=vnum_services خدمات الأرقام الافتراضية

جلب خدمات الأرقام الافتراضية المفعّلة (الدولة، المشغّل، نوع الخدمة) مع سعر البيع النهائي بعد تطبيق نسبة ربح اللوحة.

المعاملات

مثال الاستجابة

[
  {
    "service": 14,
    "name": "Telegram - Russia - Any",
    "country": "Russia",
    "operator": "Any",
    "type": "Telegram",
    "price": "24000.00",
    "currency": "Toman"
  },
  {
    "service": 15,
    "name": "WhatsApp - USA - Verizon",
    "country": "USA",
    "operator": "Verizon",
    "type": "WhatsApp",
    "price": "48000.00",
    "currency": "Toman"
  }
]

action=vnum_buy شراء رقم افتراضي

شراء رقم افتراضي للمستخدم؛ يُخصم المبلغ من المحفظة ويبقى الرقم فعّالاً خلال مدة الصلاحية.

المعاملات

مثال الاستجابة

{
  "order": 812,
  "order_no": "VN-A7K9P2",
  "service": 14,
  "number": "+79876543210",
  "status": "Pending",
  "code": "",
  "charge": "24000.00",
  "expires_at": 1763892000,
  "remaining_seconds": 1200,
  "currency": "Toman"
}

action=vnum_status حالة الرقم ورمز التحقق

معرفة حالة الرقم ورمز التحقق من الرسالة والوقت المتبقي للصلاحية (مع تحديث من المزوّد).

المعاملات

مثال الاستجابة

{
  "order": 812,
  "order_no": "VN-A7K9P2",
  "service": 14,
  "number": "+79876543210",
  "status": "Received",
  "code": "4571",
  "sms": "Your Telegram code is 4571",
  "charge": "24000.00",
  "created_at": 1763890800,
  "expires_at": 1763892000,
  "remaining_seconds": 640,
  "currency": "Toman"
}

action=vnum_orders طلبات الأرقام الافتراضية

قائمة آخر طلبات الأرقام الافتراضية للمستخدم.

المعاملات

مثال الاستجابة

[
  {
    "order": 812,
    "order_no": "VN-A7K9P2",
    "service": 14,
    "number": "+79876543210",
    "status": "Received",
    "code": "4571",
    "charge": "24000.00",
    "created_at": 1763890800,
    "expires_at": 1763892000,
    "remaining_seconds": 640,
    "currency": "Toman"
  },
  {
    "order": 795,
    "order_no": "VN-M2X4R8",
    "service": 15,
    "number": "+13456789012",
    "status": "Expired",
    "code": "",
    "charge": "48000.00",
    "created_at": 1763804400,
    "expires_at": 1763805600,
    "remaining_seconds": 0,
    "currency": "Toman"
  }
]

action=vnum_cancel إلغاء الرقم وإرجاع المبلغ

إلغاء رقم لا يزال في حالة الانتظار وإرجاع المبلغ إلى محفظة المستخدم.

المعاملات

مثال الاستجابة

{
  "canceled": 1,
  "order": 812,
  "balance": "101000.00",
  "currency": "Toman"
}

ملاحظات مهمة

قيم حالة الطلب

Pending · Processing · In progress · Completed · Partial · Canceled · Refunded

قيم حالة الرقم الافتراضي

Pending (بانتظار الرسالة) · Received (الرمز جاهز) · Canceled · Expired (انتهت الصلاحية)

ملاحظات توكن الذكاء الاصطناعي

يُعرض رصيد التوكن في action=ai_balance ويُستهلك في action=ai_chat ويُدرج في التقرير action=ai_usage. إذا كانت خدمة التوكن معطّلة أو اتصال النموذج غير مكتمل فتُعيد هذه الأوامر الخطأ المقابل.

ملاحظات الأرقام الافتراضية

يُقرأ سعر كل خدمة من API الموقع المصدر وتُطبّق نسبة ربح اللوحة. بعد الشراء يبقى الرقم فعّالاً حتى نهاية مدة الصلاحية: استخدم action=vnum_status للحصول على رمز التحقق، وقبل وصول الرسالة يمكنك الإلغاء بـ action=vnum_cancel ليُعاد المبلغ إلى المحفظة. الأمر vnum_order اسم بديل لـ vnum_buy.

الأخطاء

عند الأخطاء تُعاد الاستجابة كـ {"error":"message"} مع رمز HTTP 200، للتوافق مع سكربتات إعادة البيع الشائعة.

كود نموذجي

PHP (cURL)

<?php
$ch = curl_init('https://novin-data.ir/api.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'key'      => 'YOUR_API_KEY',
        'action'   => 'add',
        'service'  => 12,
        'link'     => 'https://instagram.com/p/xxxxx',
        'quantity' => 1000,
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response; // {"order":23501}

Python (requests)

import requests

resp = requests.post('https://novin-data.ir/api.php', data={
    'key': 'YOUR_API_KEY',
    'action': 'vnum_status',
    'order': 812,
})
print(resp.json())

JavaScript (fetch)

const res = await fetch('https://novin-data.ir/api.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    key: 'YOUR_API_KEY',
    action: 'ai_chat',
    message: 'Write a short Instagram caption about coffee',
  }),
});
const data = await res.json();
console.log(data.reply, data.tokens);