مستندات 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 دقیقه
تمام endpoint‌های دیگر	بدون محدودیت سخت	—

محدودیت نرخ: احراز هویت به 5 تلاش در هر 15 دقیقه محدود است. سایر endpoint‌ها در حال حاضر محدودیت نرخ ندارند، اما استفاده بیش از حد ممکن است محدود شود. از فواصل درخواست معقول استفاده کنید.

مدیریت خطا

تمام خطاها یک شیء 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 — سیم‌کارت واقعی، نرخ موفقیت بالاتر. premium — سریع‌ترین تحویل (~10 ثانیه)، بالاترین نرخ موفقیت.

خرید شماره (فعال‌سازی SMS)

POST /api.php?action=buy

یک شماره مجازی برای تأیید پیامکی یک‌بار مصرف خریداری کنید. شماره به مدت 20 دقیقه فعال است. اگر پیامکی دریافت نشود، موجودی شما به‌صورت خودکار برگردانده می‌شود.

پارامتر	نوع	الزامی	توضیحات
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 سفارش اخیر شما را شامل شماره‌تلفن‌ها و کدهای پیامکی برمی‌گرداند. این endpoint را برای بررسی کدهای پیامکی دریافتی در سفارشات فعال فراخوانی کنید.

پاسخ

[ { "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 — در انتظار پیامک. completed — پیامک دریافت شد. cancelled — توسط کاربر لغو شد. refunded — بازپرداخت خودکار (پیامکی قبل از انقضا دریافت نشد). 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

یک یا چند شماره تلفن اختصاصی اجاره کنید. شماره در تمام دوره اجاره منحصراً متعلق به شماست و پیامک‌های ورودی نامحدود دریافت می‌کند.

پارامتر	نوع	الزامی	توضیحات
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")