المصادقة
جميع نقاط النهاية تتطلب Bearer token في رأس Authorization.
كيفية الحصول على مفتاح API
- سجّل الدخول إلى Proxnum وانتقل إلى صفحة الملف الشخصي
- مرّر إلى قسم «إدارة مفاتيح API»
- انقر «إنشاء مفتاح API»
- انسخ الرمز المعروض
ضمّن رمز 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، اختيارية):
serviceservice (string) — تصفية حسب رمز الخدمة (مثل ig, wa, tg)countrycountry (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."
}
الأخطاء الشائعة: 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 للتحديثات الفورية