Open in your browser for best results

Inside Facebook, number lists sometimes don’t load. Tap continue to open Proxnum in Chrome or Safari — one tap, no copying links.

مرجع API

مرجع API للمطورين

توثيق شامل لتطبيق خدمات التحقق عبر SMS. جميع الاستجابات بصيغة JSON.

ملاحظة: مرجع للمطورين والمُدمِجين. كل نقطة نهاية تتضمن الشرح والمصادقة وأمثلة الطلبات والاستجابات.

المصادقة

جميع نقاط النهاية تتطلب Bearer token في رأس Authorization.

كيفية الحصول على مفتاح API
  1. سجّل الدخول إلى Proxnum وانتقل إلى صفحة الملف الشخصي
  2. مرّر إلى قسم «إدارة مفاتيح API»
  3. انقر «إنشاء مفتاح API»
  4. انسخ الرمز المعروض

ضمّن رمز API في كل طلب:

Authorization: Bearer YOUR_API_TOKEN_HERE
Accept: application/json
Content-Type: application/json

روابط سريعة:

تنسيق الاستجابة المشترك

الأخطاء تستخدم بنية موحّدة مع حقل code. جميع الأخطاء تتبع هذا النمط:

{
  "success": false,
  "code": "no_numbers",
  "message": "No numbers available for the selected service and country"
}

نقاط النهاية

GET /api/v1/resell/price?service=&country=

الحصول على السعر الأساسي وسعر البيع لخدمة ودولة. قدّر التكلفة قبل الطلب.

المعاملات (query): service (string), country (int)

مثال طلب:

curl -s -X GET "https://proxnum.com/api/v1/resell/price?service=ig&country=6" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

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

{
  "country": "6",
  "service": "ig",
  "base_price": 0.0334,
  "sell_price": 0.1114892
}

GET /api/v1/prices

أسعار شاملة لجميع الخدمات والدول. يُرجع أسعار التكلفة وأسعار الموزّع.

المعاملات (query، اختيارية):

  • service service (string) — تصفية حسب رمز الخدمة (مثل ig, wa, tg)
  • country country (int) — تصفية حسب رمز الدولة

مثال (جميع الأسعار):

curl -s -X GET "https://proxnum.com/api/v1/prices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

مثال (تصفية حسب الدولة):

curl -s -X GET "https://proxnum.com/api/v1/prices?country=6" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

استجابة ناجحة (تصفية حسب الدولة):

{
  "success": true,
  "prices": {
    "6": {
      "ig": {
        "base_price": 0.0334,
        "sell_price": 0.1114892,
        "available": 245
      },
      "wa": {
        "base_price": 0.0389,
        "sell_price": 0.1298737,
        "available": 189
      },
      "tg": {
        "base_price": 0.0223,
        "sell_price": 0.0744551,
        "available": 521
      },
      "go": {
        "base_price": 0.0278,
        "sell_price": 0.0928206,
        "available": 312
      }
    }
  }
}

ملاحظة: الاستجابة كائن متداخل: المستوى الأول رموز الدول، الثاني رموز الخدمات. كل خدمة تحتوي base_price و sell_price و available (أو null).


POST /api/v1/resell/virtual/buy

شراء رقم مؤقت (افتراضي). يحاول تخصيص رقم وخصم من الحساب.

المحتوى (JSON): {"service":"ig","country":6}

مثال طلب:

curl -s -X POST "https://proxnum.com/api/v1/resell/virtual/buy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service":"ig","country":6}'

استجابة ناجحة (موحّدة):

{
  "success": true,
  "activation": {
    "id": 737,
    "phone": "62895406203932",
    "activation_id": "4390520873",
    "msg": "Waiting Sms",
    "date_created": "2025-11-08 21:50:34",
    "amount_paid": 0.111489,
    "status": 1
  }
}

رموز الأخطاء الشائعة:

{
  "success": false,
  "code": "no_numbers",
  "message": "No numbers available for this service in the selected country"
}

{
  "success": false,
  "code": "insufficient_balance",
  "message": "Not enough balance to place the order"
}

GET /api/v1/resell/virtual/{id}/status

التحقق من حالة التفعيل. {id} يقبل activation id من الشراء.

مثال طلب:

curl -s -X GET "https://proxnum.com/api/v1/resell/virtual/4390520873/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

نجاح (عند توفر الرمز):

{
  "success": true,
  "status": "completed",
  "code": "1234",
  "activation": { "id": 737, "phone": "628...", "activation_id": "4390520873" }
}

POST /api/v1/resell/virtual/resend

طلب إعادة إرسال/إعادة تفعيل. استخدم activation id في المحتوى.

المحتوى: {"activation_id":"4390520873"}

curl -s -X POST "https://proxnum.com/api/v1/resell/virtual/resend" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activation_id":"4390520873"}'

الاستجابة (مقبولة):

{
  "success": true,
  "message": "Resend requested; new activation created",
  "activation": { "id": 738, "activation_id": "4390520874", "phone": "628..." }
}

POST /api/v1/resell/virtual/cancel

طلب الإلغاء والاسترداد. يقيّم الخادم إمكانية الاسترداد.

المحتوى: {"activation_id":"4390520873"}

curl -s -X POST "https://proxnum.com/api/v1/resell/virtual/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activation_id":"4390520873"}'

مقبول:

{
  "success": true,
  "code": "cancel_accepted",
  "message": "Cancellation accepted, refund processed"
}

مرفوض:

{
  "success": false,
  "code": "cancel_rejected",
  "message": "Cancellation rejected — activation already completed or not refundable"
}

GET /api/v1/resell/activations

قائمة تفعيلات المستخدم (مع ترقيم). يدعم page و per_page.

curl -s -X GET "https://proxnum.com/api/v1/resell/activations?page=1&per_page=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

أرقام الإيجار

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

جميع واجهات الإيجار متاحة أيضًا بدون البادئة /resell (مثل /api/v1/rental/catalog). الكتالوج العام على /api/v1/rental/catalog لا يتطلب رمزًا.

تحتوي استجابات الإيجار على "ok" (true أو false)، ورمز "error" عند حدوث خطأ، و"message" مقروءة بلغة حسابك. يعكس رمز حالة HTTP النتيجة (200 نجاح، 202 مقبول وقيد المعالجة، 4xx مشكلة في الطلب، 503 غير متاح مؤقتًا).

حالات الإيجار

  • active — الرقم لك ويستقبل الرسائل حتى expires_at.
  • cancelling — تم طلب الإلغاء وهو بانتظار التأكيد. لم يتم أي استرداد بعد.
  • cancelled — تم تأكيد الإلغاء وإعادة amount_paid إلى رصيدك.
  • expired — انتهت مدة الإيجار.

GET /api/v1/resell/rental/catalog?country=&hours=

يعيد مدد الإيجار المتاحة حاليًا والدول والخدمات مع سعرك والمخزون لدولة ومدة محددتين. تأتي قائمة المدد مباشرة من مصدر أرقامنا، لذا اقرأها دائمًا من durations[] بدلًا من تثبيت القيم في الكود.

معاملات الاستعلام: country (اختياري، رقم الدولة، راجع صفحة رموز الدول) وhours (اختياري، إحدى قيم durations[].hours). تُستبدل القيم غير الصالحة أو المفقودة بالقيم الافتراضية الواردة في الاستجابة.

مثال طلب:

curl -s "https://proxnum.com/api/v1/resell/rental/catalog?country=187&hours=168" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
{
  "ok": true,
  "country": "187",
  "hours": 168,
  "durations": [
    { "hours": 24, "label": "1 day" },
    { "hours": 72, "label": "3 days" },
    { "hours": 168, "label": "1 week" },
    { "hours": 720, "label": "30 days" }
  ],
  "countries": [ { "id": "187", "name": "USA" }, { "id": "16", "name": "United Kingdom" } ],
  "services": [
    { "code": "wa", "name": "WhatsApp", "icon": "...", "price": 4.2, "stock": 35 }
  ],
  "cancel_window_seconds": 120
}

POST /api/v1/resell/rental/buy

يستأجر رقمًا ويخصم من رصيدك. يجب أن تكون hours إحدى قيم durations[].hours من الكتالوج. يمكنك اختياريًا إرسال max_price: إذا كان السعر الحالي أعلى، فلن يُخصم شيء وستتلقى الخطأ price_changed مع السعر الجديد.

المحتوى (JSON): {"service":"wa","country":187,"hours":168,"max_price":4.20}

curl -s -X POST "https://proxnum.com/api/v1/resell/rental/buy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"service":"wa","country":187,"hours":168,"max_price":4.20}'
{
  "ok": true,
  "error": null,
  "message": "Your rental number is ready.",
  "price": 4.2,
  "balance": 25.8,
  "rental": {
    "id": 512,
    "phone": "14155550123",
    "service": "wa",
    "service_name": "WhatsApp",
    "country": "187",
    "country_name": "USA",
    "status": "active",
    "amount_paid": 4.2,
    "hours": 168,
    "purchased_at": "2026-10-03T12:00:00+03:00",
    "expires_at": "2026-10-10T12:00:00+03:00",
    "cancel_until": "2026-10-03T12:02:00+03:00",
    "can_cancel": true,
    "cancel_pending": false,
    "can_extend": true
  }
}

الأخطاء الشائعة: invalid_period (422)، no_numbers (409)، price_changed (409)، insufficient_funds (402)، option_unavailable (422)، unavailable أو provider_unreachable (503، لم يتم الخصم).


GET /api/v1/resell/rental/{id}/status

يعيد الإيجار مع الرسائل المستلمة (الأحدث أولًا). تتضمن كل رسالة النص، والرمز code عند اكتشافه. استعلم كل 5 إلى 10 ثوانٍ أثناء انتظار رسالة. يمكن أن يكون id رقم الإيجار لدينا أو رقم التفعيل المعاد عند الشراء.

curl -s "https://proxnum.com/api/v1/resell/rental/512/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
{
  "ok": true,
  "rental": {
    "id": 512,
    "phone": "14155550123",
    "status": "active",
    "expires_at": "2026-10-10T12:00:00+03:00",
    "can_cancel": false,
    "can_extend": true,
    "messages": [
      { "id": 9001, "sender": "WhatsApp", "text": "Your WhatsApp code: 123-456", "code": "123456", "date": "2026-10-03T12:05:10+03:00" }
    ]
  }
}

POST /api/v1/resell/rental/cancel

يمكن إلغاء الإيجار فقط خلال دقيقتين من الشراء، إذا لم يستقبل أي رسالة ولم يتم تمديده. يتم تأكيد الإلغاء مع مورد الأرقام، وقد يستغرق ذلك بضع دقائق.

المحتوى: {"id":512}

curl -s -X POST "https://proxnum.com/api/v1/resell/rental/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"id":512}'
HTTP/1.1 202 Accepted
{
  "ok": true,
  "pending": true,
  "refunded": 0,
  "message": "Cancellation requested. Your refund will be added once the cancellation is confirmed, usually within a few minutes.",
  "rental": { "id": 512, "status": "cancelling", "cancel_pending": true }
}

HTTP/1.1 200 OK
{
  "ok": true,
  "pending": false,
  "refunded": 4.2,
  "balance": 30,
  "rental": { "id": 512, "status": "cancelled" }
}

HTTP/1.1 409 Conflict
{
  "ok": false,
  "error": "sms_received",
  "message": "This number has already received an SMS, so it cannot be cancelled."
}
الاستجابة HTTP 202 مع "pending": true تعني أن الطلب قُبل لكن الاسترداد لم يتم بعد. استعلم عن واجهة الحالة: تصبح status إلى cancelled عند استرداد amount_paid، أو تعود إلى active إذا رُفض الإلغاء (مثلًا بسبب وصول رسالة في الأثناء). لا يتم الاسترداد أبدًا قبل التأكيد، ولا مرتين أبدًا.

الأخطاء الشائعة: window_closed، sms_received، extended، cancel_pending (طلب قيد المعالجة بالفعل)، not_active (جميعها 409).


GET /api/v1/resell/rental/{id}/extend-options

يسرد مدد التجديد وأسعارها المتاحة لإيجار نشط واحد. تُقرأ الأسعار مباشرة لهذا الرقم تحديدًا.

curl -s "https://proxnum.com/api/v1/resell/rental/512/extend-options" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{
  "ok": true,
  "options": [
    { "hours": 24, "label": "1 day", "price": 1.1 },
    { "hours": 168, "label": "1 week", "price": 5.0 }
  ]
}

POST /api/v1/resell/rental/{id}/extend

يمدد إيجارًا نشطًا بإحدى المدد المعادة من خيارات التمديد ويخصم من رصيدك. أرسل max_price لضمان عدم الخصم أبدًا بأكثر من السعر الذي عرضته على عميلك. لا يمكن إلغاء الإيجارات الممددة.

المحتوى (JSON): {"hours":168,"max_price":5.00}

curl -s -X POST "https://proxnum.com/api/v1/resell/rental/512/extend" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"hours":168,"max_price":5.00}'

{
  "ok": true,
  "message": "Rental extended by 1 week.",
  "price": 5,
  "balance": 25,
  "rental": { "id": 512, "status": "active", "expires_at": "2026-10-17T12:00:00+03:00", "can_cancel": false }
}

الأخطاء الشائعة: invalid_period (422)، price_changed (409)، insufficient_funds (402)، not_active (409)، unavailable (503).


GET /api/v1/resell/rentals

قائمة مقسمة إلى صفحات لإيجاراتك، الأحدث أولًا. معاملات الاستعلام: page وper_page (من 1 إلى 100).

curl -s "https://proxnum.com/api/v1/resell/rentals?page=1&per_page=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{ "ok": true, "total": 3, "page": 1, "per_page": 25, "data": [ { "id": 512, "phone": "14155550123", "status": "active", "...": "..." } ] }

ملاحظات التطبيق

  • عمليات الخصم idempotent لكل طلب؛ تحقق من حقول order أو transaction.
  • استخدم endpoint price لتقدير التكلفة قبل الطلب.
  • رموز الأخطاء: no_numbers, insufficient_balance, service_unavailable, cancel_rejected.
أفضل الممارسات:
  • عالج دائماً الاستجابات الناجحة والفاشلة
  • نفّذ معالجة انتهاء مهلة الشبكة
  • خزّن مؤقتاً قوائم الدول والخدمات
  • استخدم webhooks للتحديثات الفورية

chat us