API التحقق عبر الرسائل القصيرة — الرصيد والأسعار المباشرة

البدء #

كل شيء بصيغة JSON عبر HTTPS، يُوثَّق بمفتاح واحد يُنشأ بنفسك. لا حاجة إلى تثبيت SDK، ولا إلى توقيع عقد، ولا إلى طلب بيئة تجريبية — يكفي مفتاح وأداة curl.

1 إنشاء مفتاح افتح قائمة الحساب، ثم مفتاح API، ثم إنشاء مفتاح. يظهر المفتاح مرة واحدة فقط: نخزّن بصمته فقط، فلا يمكن الاطلاع عليه مرة أخرى بعد ذلك.
2 أرسِله كرمز Bearer يحمل كل طلب ترويسة Authorization. لا وسيلة دخول أخرى — لا مفتاح في سلسلة الاستعلام، ولا ملف تعريف ارتباط، ولا جلسة.
3 قراءة الاستجابة كل استجابة هي كائن JSON يتضمّن حقل ok. وحين تكون قيمة ok هي false، يوضّح حقل error السبب بسلسلة نصية ثابتة قابلة للقراءة آليًا.

المصادقة #

مفتاح واحد لكل حساب. إرساله بأي طريقة غير الترويسة أدناه غير مدعوم — فالمفتاح ضمن سلسلة الاستعلام ينتهي في سجلات الخادم، وسجل التصفح، وترويسات referrer، لذا يُرفض بدل أن يُقبل بصمت.

request

Authorization: Bearer sk_your_key_here

المفتاح يمكن أن يُنفق مالًا يقرأ اليوم الرصيد فقط، وهو نفسه المفتاح الذي سيطلب الأرقام حين تتوفر خاصية الطلب. تعامل معه كما تتعامل مع كلمة مرور: بعيدًا عن أنظمة إدارة الشيفرة المصدرية، وبعيدًا عن لقطات الشاشة، ويُستبدل بدل أن يُشارك. استبدال المفتاح يُغلق المفتاح القديم فورًا.

الاصطلاحات #

الاصطلاحات
العنوان الأساسي	https://simsms.com/api/v1
النقل	HTTPS فقط. يُعاد توجيه HTTP العادي، ولا يحمل إعادة التوجيه ترويستك.
الصيغة	JSON عند الإدخال وJSON عند الإخراج. كل استجابة هي كائن، وليست مصفوفة مجردة أبدًا.
النجاح	HTTP 200 مع "ok": true.
الفشل	رمز من فئة 4xx أو 5xx مع "ok": false وسلسلة "error" ثابتة.
الأموال	الأرقام بالدولار الأمريكي، أبدًا كسلاسل نصية، وأبدًا بالسنتات. 0.84 تعني 84 سنتًا.
الحقول غير المعروفة	قد تُضاف حقول جديدة إلى أي استجابة. تجاهل ما لا تعرفه بدل أن يتسبب في فشل.

الأخطاء #

سلسلة error هي الجزء الذي يُبنى عليه التفريع في الشيفرة. أما الجملة المرافقة لها فموجّهة إليك أنت، لا إلى شيفرتك — قد تُعاد صياغتها، أما السلسلة فلن تتغيّر.

الأخطاء
HTTP	خطأ	متى
401	`missing_key`	لا ترويسة Authorization، أو أنها ليست رمز Bearer.
401	`bad_key`	المفتاح غير معروف، أو أُغلق أو استُبدل.
400	`unknown_service`	لا خدمة بهذا الرمز. الرموز تأتي من الكتالوج، لا من اسم العرض.
404	`no_stock`	لا يوجد حاليًا رقم متوفر لهذا الزوج من الخدمة والدولة. الرقم حيّ ومتغيّر — وقد يعود التوافر لاحقًا.
404	`unknown_country`	لا دولة بهذا الرمز على هذا المنتج. لكتالوج البروكسي وكتالوج الاستئجار قائمة خاصة بكل منهما — استدعِ المسار بلا تحديد دولة للحصول عليها.
400	`unknown_tech`	لا جيل شبكة بهذا الاسم في تلك الدولة. الولايات المتحدة وحدها تبيع كلًا من 4G و5G.
429	`rate_limited`	عدد الطلبات كبير جدًا. ترويسة Retry-After توضّح عدد الثواني الواجب انتظارها.

حدود معدل الطلبات #

600 طلب في الدقيقة، محسوبة لكل حساب لا لكل عنوان. المفتاح مصمم للعمل من خادم واحد — عنوان واحد — لذا فإن حدًّا لكل عنوان سيعاقب الاستخدام العادي، ويسمح لمفتاح مسروق بالعمل بحرية من مكان آخر. عند تجاوز الحد تحصل على 429 وترويسة Retry-After بالثواني.

نقاط النهاية #

قراءات الحساب والكتالوج. كل مسار يسرد كل معامل يقبله، وكل حقل يُعيده، وكل خطأ يمكن أن يردّ به — بلا سلوك غير موثّق.

قراءة رصيدك #

GET /api/v1/balance

ما يملكه الحساب الآن، وعدد الرموز التي يشتريها هذا المبلغ بأرخص سعر متاح حاليًا في الكتالوج.

حقول الاستجابة

قراءة رصيدك — حقول الاستجابة
الحقل	النوع	الوصف
`ok`	boolean	دائمًا true عند 200.
`balance`	number	الدولارات المتاحة، مقرَّبة إلى أقرب سنت.
`currency`	string	دائمًا "USD". موجودة حتى لا تضطر إلى افتراضها.
`codes_at_cheapest`	integer	عدد الرموز التي يشتريها الرصيد بأرخص سعر في الكتالوج. تقدير تقريبي لا عرض سعر مُلزم — والقيمة null إذا كان الكتالوج فارغًا.
`cheapest_code`	number	ذلك السعر الأرخص، بحيث يمكنك حساب التقدير بنفسك مقابل رقم آخر.

الطلب

request

curl -s "https://simsms.com/api/v1/balance" \
  -H "Authorization: Bearer $SIMSMS_KEY"

الاستجابة

200 OK

{
  "ok": true,
  "balance": 42.5,
  "currency": "USD",
  "codes_at_cheapest": 425,
  "cheapest_code": 0.1
}

يمكن أن يردّ بـ missing_key bad_key rate_limited

سعر خدمة واحدة في دولة واحدة #

GET /api/v1/pricing?service={service}&country={country}

السعر الحي ومقدار التوافر الحي لزوج واحد. كلا الرقمين يتغيّر — يتبع السعر أرخص شبكة تقدّم تلك الخدمة في تلك الدولة، ويعكس التوافر ما تُبلّغ به الشبكة الآن.

المعاملات

سعر خدمة واحدة في دولة واحدة — المعاملات
المعامل		الوصف
`service`	مطلوب	رمز الخدمة، مثل telegram. بأحرف صغيرة، من الكتالوج.
`country`	اختياري	رمز الدولة، مثل england. اتركه فارغًا للحصول على كل الدول دفعة واحدة — انظر أدناه.

حقول الاستجابة

سعر خدمة واحدة في دولة واحدة — حقول الاستجابة
الحقل	النوع	الوصف
`ok`	boolean	دائمًا true عند 200.
`service`	string	رمز الخدمة الذي طلبته، يُعاد كما هو.
`country`	string	رمز الدولة الذي طلبته، يُعاد كما هو.
`price`	number	الدولارات مقابل رمز واحد، بسعر أرخص شبكة تملكه.
`stock`	integer	الأرقام المُبلَّغ عن توفرها الآن. رقم حيّ يتغيّر باستمرار.

الطلب

request

curl -s "https://simsms.com/api/v1/pricing?service=telegram&country=england" \
  -H "Authorization: Bearer $SIMSMS_KEY"

الاستجابة

200 OK

{
  "ok": true,
  "service": "telegram",
  "country": "england",
  "price": 0.84,
  "stock": 61213
}

يمكن أن يردّ بـ missing_key bad_key unknown_service no_stock rate_limited

سعر خدمة واحدة في كل مكان #

GET /api/v1/pricing?service={service}

احذف الدولة لتحصل على كل دولة تقدّم الخدمة. الترتيب خاص بالموقع: ما يُسلَّم فعليًا أولًا، ثم الأرخص ضمن ذلك — لا السعر الخام، الذي كان سيضع في الأعلى رقمًا بسنتين لا يستلم منه أحد رمزًا.

المعاملات

سعر خدمة واحدة في كل مكان — المعاملات
المعامل		الوصف
`service`	مطلوب	رمز الخدمة، مثل telegram.

حقول الاستجابة

سعر خدمة واحدة في كل مكان — حقول الاستجابة
الحقل	النوع	الوصف
`ok`	boolean	دائمًا true عند 200.
`service`	string	رمز الخدمة الذي طلبته.
`name`	string	الاسم المعروض، مثلًا «Telegram».
`countries`	array	كائن واحد لكل دولة، بالترتيب الموضح أعلاه.
`countries[].country`	string	رمز الدولة، لإعادة استخدامه في طلب الإقران.
`countries[].name`	string	اسمها بالإنجليزية.
`countries[].price`	number	السعر بالدولار لرمز واحد.
`countries[].stock`	integer	الأرقام المتاحة الآن.

الطلب

request

curl -s "https://simsms.com/api/v1/pricing?service=telegram" \
  -H "Authorization: Bearer $SIMSMS_KEY"

الاستجابة

200 OK

{
  "ok": true,
  "service": "telegram",
  "name": "Telegram",
  "countries": [
    { "country": "england", "name": "United Kingdom", "price": 0.84, "stock": 61213 },
    { "country": "poland",  "name": "Poland",         "price": 0.91, "stock": 22140 }
  ]
}

يمكن أن يردّ بـ missing_key bad_key unknown_service rate_limited

تسعير بروكسي محمول #

GET /api/v1/proxy-pricing?country={country}&tech={tech}

بلا تحديد دولة، تظهر الدول الأربع التي تعمل فيها المودمات، مع عدد المشغّلين وسعر الدخول لكل واحدة. ومع تحديد دولة، يظهر كل مشغّل فيها وسعر كل مدة. المدد بالأيام: 1، 7، 30، 365.

المعاملات

تسعير بروكسي محمول — المعاملات
المعامل		الوصف
`country`	اختياري	رمز الدولة، مثلًا us. حذفه يعرض قائمة الدول.
`tech`	اختياري	جيل الشبكة، 4g أو 5g. الولايات المتحدة وحدها تبيع الجيلين؛ وفي غيرها يُهمَل هذا الحقل، وتُعاد الفئة السعرية الوحيدة المتاحة.

حقول الاستجابة

تسعير بروكسي محمول — حقول الاستجابة
الحقل	النوع	الوصف
`ok`	boolean	القيمة true دائمًا عند استجابة 200.
`country`	string	الدولة المطلوبة.
`tech`	string	الجيل الذي جرى تسعيره فعليًا، بعد تطبيق القيمة الافتراضية.
`techs`	array	كل الأجيال المتوفرة للبيع في تلك الدولة.
`terms`	array	المدد المتاحة للبيع، بالأيام.
`carriers`	array	كائن واحد لكل مشغّل.
`carriers[].carrier`	string	رمز المشغّل، لاستخدامه في الطلب.
`carriers[].name`	string	الاسم المعروض، مثلًا «T-Mobile».
`carriers[].prices`	object	السعر بالدولار لكل مدة، مفهرَس بعدد الأيام.

الطلب

request

curl -s "https://simsms.com/api/v1/proxy-pricing?country=us" \
  -H "Authorization: Bearer $SIMSMS_KEY"

الاستجابة

200 OK

{
  "ok": true,
  "country": "us",
  "tech": "4g",
  "techs": ["4g", "5g"],
  "terms": [1, 7, 30, 365],
  "carriers": [
    { "carrier": "us-t-mobile", "name": "T-Mobile", "prices": { "1": 8.67, "7": 52, "30": 130, "365": 1300 } },
    { "carrier": "us-verizon",  "name": "Verizon",  "prices": { "1": 8.67, "7": 52, "30": 130, "365": 1300 } }
  ]
}

يمكن أن يردّ بـ missing_key bad_key unknown_country unknown_tech rate_limited

تسعير رقم للاستئجار #

GET /api/v1/rental-pricing?country={country}&days={days}

بلا تحديد دولة، تظهر كل الدول التي يمكن الاحتفاظ برقم فيها، مع سعر الدخول لكل واحدة. ومع تحديد دولة، يظهر كل مشغّل فيها وتكلفة المدة المطلوبة.

المعاملات

تسعير رقم للاستئجار — المعاملات
المعامل		الوصف
`country`	اختياري	رمز الدولة، مثلًا fr. حذفه يعرض قائمة الدول.
`days`	اختياري	المدة بالأيام: 7 أو 14 أو 30. أي قيمة أخرى تُستبدل بأقصر مدة.

حقول الاستجابة

تسعير رقم للاستئجار — حقول الاستجابة
الحقل	النوع	الوصف
`ok`	boolean	القيمة true دائمًا عند استجابة 200.
`country`	string	الدولة المطلوبة.
`days`	integer	المدة التي جرى تسعيرها فعليًا.
`terms`	array	كل المدد المتاحة للبيع، بالأيام.
`operators`	array	كائن واحد لكل مشغّل، الأرخص أولًا.
`operators[].operator`	string	رمز المشغّل، لاستخدامه في الطلب.
`operators[].name`	string	الاسم المعروض.
`operators[].type`	string	physical أو virtual أو premium.
`operators[].price`	number	السعر بالدولار للمدة كاملة.

الطلب

request

curl -s "https://simsms.com/api/v1/rental-pricing?country=fr&days=30" \
  -H "Authorization: Bearer $SIMSMS_KEY"

الاستجابة

200 OK

{
  "ok": true,
  "country": "fr",
  "days": 30,
  "terms": [7, 14, 30],
  "operators": [
    { "operator": "fr-lycamobile", "name": "Lycamobile", "type": "virtual",  "price": 14.32 },
    { "operator": "fr-orange",     "name": "Orange",     "type": "physical", "price": 20.76 }
  ]
}

يمكن أن يردّ بـ missing_key bad_key unknown_country rate_limited

أمثلة كاملة #

برامج كاملة قابلة للتشغيل، لا مقتطفات من سطر واحد — بما في ذلك الأمرين اللذين تُغفلهما المقتطفات دائمًا: معالجة صيغة الخطأ، والتراجع عند الرمز 429.

Shell #

العثور على أرخص دولة للخدمة، ثم التحقق من أن الرصيد يكفي لتغطيتها.

cheapest.sh

#!/usr/bin/env bash
set -euo pipefail
: "${SIMSMS_KEY:?export your key first}"
API="https://simsms.com/api/v1"

auth=(-H "Authorization: Bearer $SIMSMS_KEY")

# The catalogue is already ordered: the first country is the one to take.
best=$(curl -sf "${API}/pricing?service=telegram" "${auth[@]}" \
        | jq -r ".countries[0] | \"\(.country) \(.price)\"")
country=${best% *}
price=${best#* }

balance=$(curl -sf "${API}/balance" "${auth[@]}" | jq -r .balance)

# ⚠️ Compare as numbers, not as strings: "9.5" > "10" is true in a string sort.
if awk "BEGIN{exit !($balance >= $price)}"; then
  echo "ok: $country at \$$price, balance \$$balance"
else
  echo "top up first: need \$$price, have \$$balance" >&2
  exit 1
fi

JavaScript #

الأمر نفسه بلغة Node، مع معالجة صحيحة لشكل الخطأ.

pricing.mjs

const API = "https://simsms.com/api/v1";
const key = process.env.SIMSMS_KEY;

async function call(path) {
  const r = await fetch(API + path, {
    headers: { Authorization: `Bearer ${key}` },
  });
  const body = await r.json();
  // A non-2xx always carries { ok:false, error }. Branch on `error`, never on
  // the sentence — the string is stable, the wording is not.
  if (!r.ok || !body.ok) {
    if (body.error === "rate_limited") {
      const wait = Number(r.headers.get("Retry-After") || 60);
      await new Promise((s) => setTimeout(s, wait * 1000));
      return call(path);
    }
    throw new Error(body.error ?? `http_${r.status}`);
  }
  return body;
}

const { countries } = await call("/pricing?service=telegram");
const { balance }   = await call("/balance");

const best = countries[0];
console.log(`${best.name}: $${best.price} (${best.stock} in stock)`);
console.log(balance >= best.price ? "balance covers it" : "top up first");

Python #

وبلغة Python أيضًا، مع إعادة المحاولة نفسها عند 429.

pricing.py

import os, time, requests

API = "https://simsms.com/api/v1"
S = requests.Session()
S.headers["Authorization"] = f"Bearer {os.environ['SIMSMS_KEY']}"

def call(path):
    r = S.get(API + path, timeout=20)
    body = r.json()
    if not r.ok or not body.get("ok"):
        if body.get("error") == "rate_limited":
            time.sleep(int(r.headers.get("Retry-After", 60)))
            return call(path)
        raise RuntimeError(body.get("error", f"http_{r.status_code}"))
    return body

countries = call("/pricing?service=telegram")["countries"]
balance   = call("/balance")["balance"]

best = countries[0]
print(f"{best['name']}: ${best['price']} ({best['stock']} in stock)")
print("balance covers it" if balance >= best["price"] else "top up first")

خارطة الطريق #

تغطي واجهة API اليوم قراءة الحساب والكتالوج. والخطوة التالية هي واجهة الطلب، وستكون ضمن العنوان الأساسي نفسه وباستخدام المفتاح نفسه — ولا حاجة لإعادة كتابة أي شيء يُبنى الآن.

طلب رقم	مخطَّط مخطَّط له. الطلب يتم عبر الموقع حاليًا.
الاستعلام عن الرمز	مخطَّط مخطَّط له، إلى جانب الطلب.
تحرير رقم	مخطَّط مخطَّط له، إلى جانب الطلب.
الاستئجار عبر API	مخطَّط مخطَّط له.
استدعاءات الويب	مخطَّط مخطَّط له، حالما تتوفر أحداث الطلب لإرسالها.

تنمو هذه الصفحة معها: الأقسام أدناه تبقى في مكانها، وتُضاف أقسام جديدة تحت نقاط النهاية.

سجل التغييرات #

2026-08-22النسخة العلنية الأولى: المفاتيح، GET /balance، GET /pricing.