وثائق API

أتمتة سير عمل التحقق عبر SMS باستخدام واجهة API الخاصة بـ SimNoKYC. اشترِ أرقام هواتف افتراضية، واستلم رموز SMS، واستأجر أرقامًا مخصصة، وأدر الطلبات — كل ذلك برمجيًا.

المصادقة

تستخدم API مصادقة الجلسة القائمة على ملفات تعريف الارتباط. للمصادقة برمجيًا:

أرسل طلب POST إلى /auth-api.php مع عبارة seed الخاصة بك
خزّن ملف تعريف ارتباط الجلسة من الاستجابة
أدرج ملف تعريف الارتباط في جميع طلبات API اللاحقة

POST /auth-api.php

قم بالمصادقة باستخدام عبارة seed الخاصة بك وأنشئ جلسة.

المعامل	النوع	مطلوب	الوصف
action	string	مطلوب	يجب أن يكون `"login"`
seed	string	مطلوب	عبارة seed الوصول المكونة من 16 حرفًا (مثال: `AbC3-dEf4-gHj5-kLm6`)

cURL
Python
JavaScript
# Login and save session cookie
curl -X POST https://simnokyc.com/auth-api.php \
  -d "action=login&seed=AbC3-dEf4-gHj5-kLm6" \
  -c cookies.txt
import requests

session = requests.Session()
resp = session.post("https://simnokyc.com/auth-api.php", data={
    "action": "login",
    "seed": "AbC3-dEf4-gHj5-kLm6"
})
data = resp.json()
print(data)  # {"success": true, "user": {...}}

# session object now holds the cookie for all future requests
const resp = await fetch("https://simnokyc.com/auth-api.php", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: "action=login&seed=AbC3-dEf4-gHj5-kLm6"
});
const data = await resp.json();
console.log(data); // {success: true, user: {...}}

استجابة ناجحة

{ "success": true, "user": { "id": 42, "prefix": "AbC3", "balance": "74.50" } }

استجابة خطأ

{ "success": false, "error": "Invalid seed." }

الرابط الأساسي

جميع نقاط نهاية API نسبية إلى:

https://simnokyc.com/api.php?action={action}

جميع الاستجابات بتنسيق JSON. تقبل نقاط نهاية POST أجسام الطلبات application/json و application/x-www-form-urlencoded.

حدود الطلبات

تفرض API حدود المعدل التالية:

نقطة النهاية	الحد	النافذة
المصادقة	5 محاولات	15 دقيقة
جميع endpoints الأخرى	بدون حد صارم	—

تحديد المعدل: المصادقة محدودة بـ 5 محاولات كل 15 دقيقة. endpoints الأخرى غير محدودة حاليًا، لكن الاستخدام المفرط قد يتم تقييده. استخدم فترات طلب معقولة.

معالجة الأخطاء

تُرجع جميع الأخطاء كائن JSON مع حقل <code>error</code>:

{ "error": "Description of what went wrong" }

رمز HTTP	المعنى
200	نجاح (تحقق من نص الاستجابة لأخطاء مستوى التطبيق)
403	رمز CSRF غير صالح
405	طريقة HTTP خاطئة (مثال: GET على endpoint يقبل POST فقط)
429	تم تجاوز حد المعدل

أخطاء شائعة على مستوى التطبيق:

خطأ	السبب
`"Login required"`	انتهت الجلسة أو غير مصادق عليه
`"Insufficient balance"`	أموال غير كافية — يتضمن حقلي `need` و`have`
`"Service not available for this country"`	لا يوجد مخزون أو الخدمة غير نشطة للدولة المحددة
`"Missing country or service"`	لم يتم تقديم المعاملات المطلوبة

قائمة الدول

GET /api.php?action=countries

يُرجع جميع الدول النشطة مع الأرقام الافتراضية المتاحة. لا يتطلب مصادقة.

cURL
Python
JavaScript
curl https://simnokyc.com/api.php?action=countries
resp = session.get("https://simnokyc.com/api.php", params={"action": "countries"})
countries = resp.json()
for c in countries:
    print(c["code"], c["name"])
const resp = await fetch("https://simnokyc.com/api.php?action=countries");
const countries = await resp.json();

الاستجابة

[ { "id": 1, "code": "us", "name": "USA" }, { "id": 2, "code": "gb", "name": "UK" }, { "id": 3, "code": "de", "name": "Germany" } ]

قائمة الخدمات

GET /api.php?action=services&country={code}

يُرجع الخدمات المتاحة لدولة محددة، بما في ذلك الأسعار والمخزون. بدون رمز الدولة، يُرجع جميع الخدمات بدون أسعار.

المعامل	النوع	مطلوب	الوصف
country	string	اختياري	رمز الدولة ISO 3166-1 alpha-2 (مثال: `us`، `gb`، `de`)

الاستجابة (مع الدولة)

[ { "id": 12, "name": "WhatsApp", "slug": "whatsapp", "icon_code": "WA", "icon_color": "#25d366", "category": "social", "price": "0.35", "stock": 847 } ]

قائمة المشغّلين

GET /api.php?action=operators&country={code}

يُرجع المشغلين (الناقلين) المتاحين لدولة محددة. لكل مشغل نوع ومضاعف سعر يُطبق على سعر الخدمة الأساسي.

المعامل	النوع	مطلوب	الوصف
country	string	مطلوب	رمز الدولة ISO 3166-1 alpha-2

الاستجابة

[ { "id": 5, "name": "T-Mobile", "type": "physical", "price_multiplier": "1.50", "icon_slug": "tmobile", "icon_domain": "t-mobile.com" } ]

أنواع المشغلين: virtual — أرقام VoIP، الأرخص، قد تُحظر من بعض الخدمات. physical — بطاقات SIM حقيقية، معدل نجاح أعلى. premium — أسرع تسليم (~10 ثوانٍ)، أعلى معدل نجاح.

شراء رقم (تفعيل SMS)

POST /api.php?action=buy

اشترِ رقمًا افتراضيًا للتحقق عبر SMS لمرة واحدة. الرقم نشط لمدة 20 دقيقة. إذا لم يتم استلام أي SMS، يتم استرداد رصيدك تلقائيًا.

المعامل	النوع	مطلوب	الوصف
country	string	مطلوب	رمز الدولة (مثال: `us`)
service_id	integer	مطلوب	معرّف الخدمة من قائمة الخدمات
operator_id	integer	اختياري	معرّف المشغل من قائمة المشغلين. اتركه فارغًا للمشغل الافتراضي.

cURL
Python
JavaScript
curl -X POST https://simnokyc.com/api.php?action=buy \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"country":"us","service_id":12,"operator_id":5}'
resp = session.post("https://simnokyc.com/api.php?action=buy", json={
    "country": "us",
    "service_id": 12,
    "operator_id": 5
})
order = resp.json()
print(f"Order #{order['order_id']} — ${order['price']}")
const resp = await fetch("https://simnokyc.com/api.php?action=buy", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ country: "us", service_id: 12, operator_id: 5 })
});
const order = await resp.json();

استجابة ناجحة

{ "success": true, "order_id": 1847, "price": 0.53, "balance": "73.97" }

خطأ: رصيد غير كافٍ

{ "error": "Insufficient balance", "need": 0.53, "have": "0.10" }

عرض الطلبات

GET /api.php?action=orders

يُرجع أحدث 50 طلبًا لك، بما في ذلك أرقام الهواتف ورموز SMS. استعلم عن هذا endpoint للتحقق من رموز SMS الواردة على الطلبات النشطة.

الاستجابة

[ { "id": 1847, "price": "0.53", "status": "completed", "phone_number": "+12025551234", "sms_code": "847293", "created_at": "2026-04-09 14:32:00", "country_code": "us", "country_name": "USA", "service_name": "WhatsApp", "operator_name": "T-Mobile" } ]

حالات الطلب: active — بانتظار SMS. completed — تم استلام SMS. cancelled — ألغاه المستخدم. refunded — استرداد تلقائي (لم يتم استلام SMS قبل انتهاء المهلة). expired — انتهت المهلة.

الحصول على سعر الإيجار

GET /api.php?action=rental_price&country={code}&operator_id={id}&duration={days}

احصل على سعر استئجار رقم مخصص من مشغل محدد لفترة معينة.

المعامل	النوع	مطلوب	الوصف
country	string	مطلوب	رمز الدولة
operator_id	integer	مطلوب	معرّف المشغل
duration	integer	مطلوب	مدة الإيجار بالأيام: `7`، `14`، `30`، أو `90`

الاستجابة

{ "price": "12.50", "duration": 30, "operator": "T-Mobile", "type": "physical", "country": "USA" }

استئجار رقم

POST /api.php?action=rental_buy

استأجر رقم هاتف مخصصًا واحدًا أو أكثر. الرقم حصري لك طوال فترة الإيجار ويستقبل رسائل SMS واردة غير محدودة.

المعامل	النوع	مطلوب	الوصف
country	string	مطلوب	رمز الدولة
operator_id	integer	مطلوب	معرّف المشغل
duration	integer	مطلوب	`7`، `14`، `30`، أو `90` يومًا
qty	integer	اختياري	عدد الأرقام للاستئجار (1–10، الافتراضي: 1)

استجابة ناجحة

{ "success": true, "order_ids": [1848, 1849], "total": 25.00, "qty": 2, "unit_price": 12.50, "duration": 30, "balance": "49.50" }

الحصول على معلومات المستخدم

GET /api.php?action=user

يُرجع معلومات حساب المستخدم الحالي والرصيد. استخدمه للتحقق من حالة المصادقة والأموال المتاحة.

مصادق عليه

{ "logged_in": true, "id": 42, "prefix": "AbC3", "balance": "74.50" }

غير مصادق عليه

{ "logged_in": false }

مثال على سير العمل الكامل

إليك مثال Python كامل يقوم بالمصادقة، ويجد خدمة، ويشتري رقمًا، ويستعلم عن رمز SMS:

Python
import requests, time

BASE = "https://simnokyc.com"
SEED = "AbC3-dEf4-gHj5-kLm6"

s = requests.Session()

# 1. Authenticate
s.post(f"{BASE}/auth-api.php", data={"action": "login", "seed": SEED})

# 2. Check balance
user = s.get(f"{BASE}/api.php?action=user").json()
print(f"Balance: ${user['balance']}")

# 3. Get services for USA
services = s.get(f"{BASE}/api.php?action=services&country=us").json()
whatsapp = next(svc for svc in services if svc["name"] == "WhatsApp")
print(f"WhatsApp: ${whatsapp['price']} ({whatsapp['stock']} in stock)")

# 4. Buy a number
order = s.post(f"{BASE}/api.php?action=buy", json={
    "country": "us",
    "service_id": whatsapp["id"]
}).json()
print(f"Order #{order['order_id']} created")

# 5. Poll for SMS code
for _ in range(60):
    orders = s.get(f"{BASE}/api.php?action=orders").json()
    my_order = next(o for o in orders if o["id"] == order["order_id"])

    if my_order["sms_code"]:
        print(f"SMS code: {my_order['sms_code']}")
        print(f"Phone:    {my_order['phone_number']}")
        break

    print("Waiting for SMS...")
    time.sleep(5)
else:
    print("Timeout — balance will be refunded automatically")