مرجع 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"

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

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

chat us