دليل ربط الشركاء — الأرقام

1نظرة عامة

أرقام هاتف لاستقبال كود التحقق (SMS): مؤقتة لتفعيلٍ واحد، أو دائمة تُستأجر لأيام.

قسم الأرقام لا يعمل كمنتجٍ عادي: الشريك يختار سيرفراً ثم خدمة (واتساب، تيليجرام…)، فيُشترى له رقم، ثم ينتظر كود التحقق الذي يصل إلى الرقم. لذلك له نداءاته الخاصة تحت /numbers، وهي تعمل بمفتاح الربط نفسه وبرصيد المحفظة نفسه وبسعر شريحتك.

كيف يجري الشراء

1. تجلب السيرفرات المتاحة الآن، وتختار واحداً (مؤقت أو دائم).
2. تجلب خدمات السيرفر بأسعارها الحيّة بشريحتك، وما تقبله كل خدمة (ولاية، مقدّمة، إلغاء…).
3. تشتري الرقم بمرجعٍ فريد من طرفك — يُخصم ثمنه من محفظتك ويعود الرقم في الرد.
4. تعرض الرقم لعميلك، وتتابع حتى يصل الكود (completed) أو يُسترَد المبلغ (refunded).

2الأساسيات والمفتاح

القواعد نفسها في الأدلة الثلاثة — مختصرةً هنا.

3البدء السريع

من صفر إلى أول كود في أربعة نداءات.

# 1) Servers available right now
curl -H "X-API-Key: axk_YOUR_KEY" https://axissstore.com/api/partner/v1/numbers/servers

# 2) Services of a server, at your tier price
curl -H "X-API-Key: axk_YOUR_KEY" "https://axissstore.com/api/partner/v1/numbers/services?server=us-temp-1&q=whatsapp"

# 3) Buy a number — with your own unique reference
curl -X POST https://axissstore.com/api/partner/v1/numbers/orders \
  -H "X-API-Key: axk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"server":"us-temp-1","service":"whatsapp","reference":"NUM-10001"}'

# 4) Ask for the code (at most once every 5 seconds per number)
curl -X POST -H "X-API-Key: axk_YOUR_KEY" https://axissstore.com/api/partner/v1/numbers/orders/NUM-10001/refresh

4السيرفرات

السيرفر يحدّد نوع الرقم (مؤقت أو دائم) ومصدره. ابدأ منه دائماً.

{
  "items": [
    { "key": "us-temp-1", "name": "رقم أمريكي مؤقت — سيرفر 1", "type": "temporary", "needs_country": false },
    { "key": "us-perm-1", "name": "رقم أمريكي دائم — سيرفر 1", "type": "permanent", "needs_country": false },
    { "key": "global-temp", "name": "رقم عالمي مؤقت", "type": "temporary", "needs_country": true }
  ],
  "total": 3
}

السيرفرات المعرّفة

قد يظهر بعضها فقط في /numbers/servers بحسب المتاح لحظة النداء.

5الخدمات والأسعار

أسعار حيّة بشريحتك، ومعها ما تقبله كل خدمة عند الشراء.

{
  "items": [{
    "name": "whatsapp",
    "label": "whatsapp",
    "price_usd": "0.62",
    "popular": true,
    "country": "",
    "duration": "",
    "durations": [],
    "state_ok": true, "area_code_ok": false,
    "cancel_ok": true, "auto_refund": true,
    "no_code_minutes": 10
  }],
  "total": 1
}

حقول الخدمة

curl -H "X-API-Key: axk_YOUR_KEY" "https://axissstore.com/api/partner/v1/numbers/quote?server=us-perm-2&service=whatsapp&duration=30d"

{ "items": [ { "code": "GB", "name": "United Kingdom", "count": 1840 } ], "total": 1 }

{ "items": [ "Alabama", "Alaska", "Arizona", "..." ], "total": 50 }

6شراء رقم

يُخصم الثمن من محفظتك ويُشترى الرقم فوراً — في نداء واحد.

curl -X POST https://axissstore.com/api/partner/v1/numbers/orders \
  -H "X-API-Key: axk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{
    "server": "us-temp-1",
    "service": "whatsapp",
    "reference": "NUM-10001",
    "us_state": "Florida"
  }'

{
  "reference": "AX-NUM-3F9A2B01",
  "partner_reference": "NUM-10001",
  "kind": "purchase", "parent": "",
  "status": "processing", "state": "waiting",
  "type": "temporary",
  "server": "us-temp-1", "service": "whatsapp",
  "name": "رقم whatsapp — رقم أمريكي مؤقت — سيرفر 1",
  "phone": "+12125550100",
  "codes": [], "latest_code": "",
  "duration": "", "country": "", "us_state": "Florida", "area_code": "",
  "expires_at": "",
  "can_cancel": true, "auto_renew": false,
  "total_usd": "0.62",
  "created_at": "2026-10-07T14:05:31.825176", "completed_at": null
}

• الرقم يعود غالباً في الرد نفسه (phone) والحالة processing — اعرضه لعميلك فوراً ليطلب الكود.
• إن رفض المصدر الشراء رفضاً مؤكَّداً (لا مخزون مثلاً) يعود الرد بـ201 والحالة refunded — المبلغ عاد لمحفظتك.
• إن كانت نتيجة المصدر غير محسومة (مهلة) يبقى الطلب processing بلا رقم، ونتابعه آلياً حتى يتّضح: رقمٌ أو استرداد.

7شكل ردّ الرقم وحالاته

كل نداءات الشراء والمتابعة والعمليات تعيد الشكل نفسه.

الحالة المالية — status

حالة الرقم — state

8استلام كود التحقق

نتابع المصدر آلياً كل نصف دقيقة تقريباً؛ ويمكنك طلب التحديث الآن.

curl -H "X-API-Key: axk_YOUR_KEY" https://axissstore.com/api/partner/v1/numbers/orders/NUM-10001

{ "reference": "AX-NUM-3F9A2B01", "partner_reference": "NUM-10001", "status": "completed", "state": "done",
  ..., "phone": "+12125550100", "codes": ["482913"], "latest_code": "482913",
  "completed_at": "2026-10-07T14:06:02.114093" }

curl -X POST -H "X-API-Key: axk_YOUR_KEY" https://axissstore.com/api/partner/v1/numbers/orders/NUM-10001/refresh

{ "items": [ { "reference": "AX-NUM-3F9A2B01", "phone": "+12125550100", "state": "waiting", ... } ], "total": 1 }

الطلب يظهر أيضاً في نداءات الطلبات العامة (GET https://axissstore.com/api/partner/v1/orders/{reference}) ونصّ التسليم فيه يحمل الرقم والأكواد — لكنّ نداءات /numbers هي التي تعيدها حقولاً منفصلة.

9الإلغاء والاسترداد

المبلغ يعود لمحفظتك حين يؤكّد المصدر الاسترداد — لا لحظة الطلب.

curl -X POST -H "X-API-Key: axk_YOUR_KEY" https://axissstore.com/api/partner/v1/numbers/orders/NUM-10001/cancel

10إعادة استخدام رقم مؤقت

كودٌ جديد على الرقم نفسه بعد اكتماله — ضمن نافذةٍ زمنية وبرسمٍ معلن.

{
  "type": "temporary", "busy": false, "expires_at": "",
  "reuse": { "price_usd": "0.35", "until": "2026-10-07T14:36" },
  "renew": null, "extend": null, "auto_renew": null
}

{
  "type": "permanent", "busy": false, "expires_at": "2026-10-14T14:05",
  "reuse": null,
  "renew": { "price_usd": "3.20", "duration": "7d", "label": "7 أيام" },
  "extend": { "durations": [ { "key": "7d", "label": "7 أيام", "days": 7 },
                             { "key": "30d", "label": "30 يوماً", "days": 30 } ] },
  "auto_renew": { "enabled": false, "hours_before": 12 }
}

curl -X POST https://axissstore.com/api/partner/v1/numbers/orders/NUM-10001/reuse \
  -H "X-API-Key: axk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"reference":"NUM-10001-R1"}'

{ "reference": "AX-NUM-77C01D2E", "partner_reference": "NUM-10001-R1",
  "kind": "reuse", "parent": "AX-NUM-3F9A2B01",
  "status": "processing", "state": "waiting", "phone": "+12125550100", "codes": [], ...,
  "total_usd": "0.35" }

11تجديد وتمديد الإيجار الدائم

كل عملية طلبٌ مستقل بثمنه ومرجعه واسترداده.

curl -X POST https://axissstore.com/api/partner/v1/numbers/orders/RENT-501/renew \
  -H "X-API-Key: axk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"reference":"RENT-501-REN-1"}'

curl -X POST https://axissstore.com/api/partner/v1/numbers/orders/RENT-501/extend \
  -H "X-API-Key: axk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"reference":"RENT-501-EXT-1","duration":"30d"}'

{ "reference": "AX-NUM-9B20E4A1", "partner_reference": "RENT-501-REN-1",
  "kind": "renew", "parent": "AX-NUM-5D11C0F7",
  "status": "completed", "phone": "+12125550100", "duration": "7d", ...,
  "total_usd": "3.20", "completed_at": "2026-10-13T09:12:44.501220" }

• عند completed يتقدّم expires_at على الرقم الأصلي — اقرأه من GET /numbers/orders/{الرقم}.
• قد تبقى العملية processing إن نفّذها المصدر على مهل — تابِعها بمرجعها حتى تُحسم.
• إن رفضها المصدر تصير refunded ويعود ثمنها، والرقم الأصلي لا يتأثر.
• رقم مؤقت لا يُجدَّد ولا يُمدَّد (422)، ولا تُقبل عمليتان معاً على الرقم نفسه.

12التجديد التلقائي

يُجدَّد الإيجار الدائم من محفظتك قبل انتهائه — دون نداءٍ منك.

curl -X PUT https://axissstore.com/api/partner/v1/numbers/orders/RENT-501/auto-renew \
  -H "X-API-Key: axk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"enabled":true}'

{ "reference": "AX-NUM-5D11C0F7", "auto_renew": true }

• متاح فقط حين يعيد options.auto_renew قيمةً غير null؛ وإلا 422. الإيقاف مقبول دائماً.
• يُجدَّد الرقم قبل انتهائه بنحو 12 ساعة، بمدته نفسها وبسعر التجديد لحظتها، ويظهر كعملية renew في طلباتك.
• إن لم يكفِ الرصيد وقتها لا يُجدَّد الرقم ويُوقَف التجديد التلقائي له (auto_renew يعود false) — راقب balance_usd، وجدّد يدوياً بعد الشحن.
• لا يحمل reference: هو إعدادٌ لا عملية مالية، وتكراره آمن.

13منع ازدواج العمليات

الشبكة تنقطع، والخصم يجب ألّا يتكرر.

• النداءات الأربعة التي تخصم مالاً — الشراء وreuse وrenew وextend — تحمل reference فريداً من طرفك. بدونه يُرفض النداء بـ422 قبل أي خصم.
• إعادة إرسال النداء نفسه بالمرجع نفسه تعيد العملية الأولى بحالتها الحالية (وبرمز 201 أيضاً) — لا رقم ثانٍ ولا خصم ثانٍ.
• عند انتهاء المهلة دون رد: أعد الإرسال بالمرجع نفسه، أو استعلم GET /numbers/orders/{reference}.
• المرجع واحدٌ لحسابك كله: مرجعٌ استُخدم لمنتج في المتجر أو لبروكسي أو لعمليةٍ أخرى على رقم لا يصلح هنا — يُرفض بـ409 conflict. استخدم بادئةً لكل نوع (NUM-، PRX-…) ولكل عملية مرجعاً جديداً.
• المرجع خاصّ بحسابك: شريكٌ آخر يستخدم المرجع نفسه لا يتعارض معك.

14الأخطاء

الصيغة نفسها في كل الواجهة — ابنِ منطقك على code لا على نص الرسالة.

HTTP/1.1 422 Unprocessable Entity
{
  "code": "validation_error",
  "message": "هذه الخدمة لا تدعم اختيار الولاية.",
  "details": {}
}

15مثال كامل

شراء رقم مؤقت ثم انتظار الكود، بمعالجة صحيحة للأخطاء وإعادة المحاولة.

Python

import os, time, requests

API = "https://axissstore.com/api/partner/v1"
HEADERS = {"X-API-Key": os.environ["AXIS_API_KEY"]}   # key from an environment variable

def call(method, path, **kw):
    for attempt in range(5):
        try:
            r = requests.request(method, API + path, headers=HEADERS, timeout=30, **kw)
        except requests.RequestException:
            time.sleep(2 ** attempt); continue          # network error: retry with the same reference
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "5"))); continue
        if r.status_code >= 500:
            time.sleep(2 ** attempt); continue
        data = r.json()
        if r.status_code >= 400:
            raise RuntimeError(f"{data['code']}: {data['message']}")
        return data
    raise RuntimeError("service unavailable")

def buy_number(server, service, shop_order_id, on_number, wait_minutes=12):
    ref = f"NUM-{shop_order_id}"                               # fixed per purchase
    number = call("POST", "/numbers/orders", json={
        "server": server, "service": service, "reference": ref})
    shown = False
    deadline = time.time() + wait_minutes * 60
    while number["status"] in ("paid", "processing") and time.time() < deadline:
        if number["phone"] and not shown:
            on_number(number["phone"]); shown = True            # show it to your customer now
        time.sleep(8)
        number = call("POST", f"/numbers/orders/{ref}/refresh")
    return number            # completed (code in latest_code), refunded, or still waiting

n = buy_number("us-temp-1", "whatsapp", 10001, on_number=print)
print(n["status"], n["phone"], n["latest_code"])

Node.js

const API = 'https://axissstore.com/api/partner/v1';
const headers = { 'X-API-Key': process.env.AXIS_API_KEY, 'Content-Type': 'application/json' };

async function axis(method, path, body) {
  const res = await fetch(API + path, { method, headers, body: body && JSON.stringify(body),
                                    signal: AbortSignal.timeout(30000) });
  const data = await res.json();
  if (!res.ok) throw new Error(`${data.code}: ${data.message}`);
  return data;
}

let number = await axis('POST', '/numbers/orders',
  { server: 'us-temp-1', service: 'whatsapp', reference: 'NUM-10001' });
console.log('number:', number.phone);
while (['paid', 'processing'].includes(number.status)) {
  await new Promise(r => setTimeout(r, 8000));
  number = await axis('POST', '/numbers/orders/NUM-10001/refresh');
}
console.log(number.status, number.latest_code);

16أفضل الممارسات وقائمة التحقق

ما يميّز ربطاً يعمل لسنوات عن ربطٍ يتعطّل عند أول انقطاع.

قبل الإطلاق

17مرجع النداءات والدعم

كل نداءات قسم الأرقام في جدول واحد.

• الدعم الفني: من صفحة «الدعم» في حسابك على https://axissstore.com — اذكر مرجع الرقم (AX-NUM-… أو مرجعك) وتوقيت النداء.
• مفاتيحك: https://axissstore.com/api-access
• هذه الوثيقة على الإنترنت: https://axissstore.com/developers/numbers

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

© 2026 AXIS GROUP — AXIS STORE. جميع الحقوق محفوظة.
هذه الوثيقة مرجعٌ تقني لشركاء AXIS STORE، وقد تُحدَّث — النسخة الأحدث دائماً على https://axissstore.com/developers/numbers.