دليل ربط الشركاء

1نظرة عامة

واجهة REST بسيطة بصيغة JSON، مصمَّمة لتُبنى عليها متاجر التجزئة والبوتات وأنظمة الموزّعين.

تتيح لك واجهة الشركاء أن تبيع منتجات AXIS STORE من داخل نظامك أنت: تجلب الكتالوج بأسعار شريحتك، وتنشئ الطلب نيابةً عن عميلك، فيُخصم ثمنه من محفظتك لدينا، ويُنفَّذ آلياً، ثم تستلم بيانات التسليم (كوداً أو تأكيد شحن) لتعرضها لعميلك.

كيف يجري الطلب

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

2من يحق له الربط

الربط البرمجي ميزة لشركائنا في الشرائح العليا، بعد موافقة الإدارة.

• اطلب الترقية من صفحة «مستواي والأسعار» في حسابك، وتُراجَع من الإدارة.
• الأسعار في الواجهة هي أسعار شريحتك لحظة الطلب: ترقيتك تخفّضها فوراً على كل نداء.
• إن سُحبت الصلاحية من شريحتك تتوقف مفاتيحك فوراً عن العمل (تُعاد 401).

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

من صفر إلى أول طلب في خمس خطوات.

1. أنشئ مفتاحاً: من حسابك ← «الربط البرمجي API» ← «مفتاح جديد». يبدأ المفتاح بـaxk_ ويُعرَض مرة واحدة فقط — احفظه فوراً في مكان آمن على خادمك.
2. اشحن محفظتك: كل طلب يُخصم من رصيد محفظتك لدينا. تأكّد من الرصيد عبر /me.
3. تحقّق من الربط: نداء GET /me يعيد اسمك وشريحتك ورصيدك.
4. اجلب منتجاً: GET /products?q=... لتعرف slug المنتج وحقوله المطلوبة.
5. أنشئ الطلب وتابعه: POST /orders بمرجعك الفريد، ثم GET /orders/{reference} حتى الاكتمال.

# 1) Verify the connection
curl -H "X-API-Key: axk_YOUR_KEY" https://store.72-61-87-107.nip.io/api/partner/v1/me

# 2) Find a product
curl -H "X-API-Key: axk_YOUR_KEY" "https://store.72-61-87-107.nip.io/api/partner/v1/products?q=pubg"

# 3) Create an order — with your own unique reference
curl -X POST https://store.72-61-87-107.nip.io/api/partner/v1/orders \
  -H "X-API-Key: axk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"product":"pubg-uc-60","quantity":1,"reference":"SHOP-10001","fields":{"player_id":"5123456789"}}'

# 4) Track its status
curl -H "X-API-Key: axk_YOUR_KEY" https://store.72-61-87-107.nip.io/api/partner/v1/orders/SHOP-10001

4أساسيات الواجهة

قواعد ثابتة تنطبق على كل نقطة نهاية.

5المصادقة وأمان المفتاح

مفتاحك يعادل محفظتك: من يملكه يستطيع الشراء برصيدك.

X-API-Key: axk_3Jq9vT2kR8...

• يُعرَض مرة واحدة عند إنشائه، ونخزّن بصمته فقط — لا نستطيع استرجاعه لك. من فقده أنشأ غيره.
• احفظه على خادمك فقط (متغيّر بيئة أو خزنة أسرار) — لا في تطبيق جوال ولا في كود متصفح ولا في مستودع كود.
• حتى 5 مفاتيح فعّالة لكل حساب — مفتاحٌ لكل نظام (متجر، بوت…) يسهّل الإلغاء المنفرد.
• الإلغاء فوري: من صفحة مفاتيحك؛ أي نظام يستخدم المفتاح يتلقى 401 من النداء التالي.
• ترى لكل مفتاح عدد النداءات وآخر استخدام — راقبها لاكتشاف أي استخدام غير متوقّع.

6حدود الاستخدام

حدودٌ سخية لكل مفتاح تحمي استقرار الخدمة للجميع.

عند تجاوز الحد تُعاد 429 مع ترويسة Retry-After (بالثواني) والحقل details.retry_after:

HTTP/1.1 429 Too Many Requests
Retry-After: 17

{"code": "rate_limited", "message": "محاولات كثيرة. أعد المحاولة بعد 17 ثانية.", "details": {"retry_after": 17}}

انتظر المدة المذكورة ثم أعد المحاولة. القيم الحالية تعيدها /me في limits — اقرأها من هناك بدل تثبيتها في كودك.

7الحساب والرصيد

أول نداء تجريه — ونقطة فحص صحة الربط.

{
  "account_no": "90111620",
  "account_seq": 1024,
  "name": "متجر النجم",
  "tier": { "key": "vip", "name": "شريك VIP", "margin_pct": "4.0000" },
  "balance_usd": "250.00",
  "balance_display": "$250.00",
  "currency": "USD",
  "api_version": "1.1",
  "limits": { "requests_per_minute": 120, "orders_per_minute": 60, "batch_max": 50 }
}

8الأقسام

لبناء قوائم التصفّح في متجرك أو لمزامنة الكتالوج قسماً قسماً.

{
  "items": [
    { "slug": "pubg-global", "name": "ببجي العالمية", "folder": "الألعاب",
      "image": "https://store.72-61-87-107.nip.io/media/...", "products_count": 12 }
  ],
  "total": 1
}

9المنتجات

كل ما تحتاجه لعرض المنتج وطلبه: السعر بشريحتك، الحقول المطلوبة، وقيود الكمية.

{
  "items": [{
    "slug": "pubg-uc-60",
    "name": "60 شدة",
    "category": "ببجي العالمية", "category_slug": "pubg-global",
    "image": "https://store.72-61-87-107.nip.io/media/...",
    "price_usd": "0.9152",
    "min_order_total_usd": "0.9152",
    "in_stock": true,
    "fields": [
      { "key": "player_id", "label": "معرّف اللاعب", "hint": "", "type": "number", "required": true }
    ],
    "min_quantity": 1, "max_quantity": 0, "quantity_step": 1,
    "allowed_quantities": [], "price_unit": 0
  }],
  "page": 1, "per_page": 50, "total": 1, "pages": 1
}

حقول المنتج

أنواع الحقول (fields[].type)

{
  "slug": "netflix-premium", "name": "نتفليكس بريميوم", ...,
  "description": "يُسلَّم خلال 5 دقائق…",
  "variants": [
    { "id": 41, "name": "شهر", "price_usd": "6.20" },
    { "id": 42, "name": "3 أشهر", "price_usd": "17.40" }
  ]
}

10التسعير المسبق

احسب ثمن الطلب الدقيق قبل إنشائه — مع التحقق من قيود الكمية.

curl -H "X-API-Key: axk_YOUR_KEY" "https://store.72-61-87-107.nip.io/api/partner/v1/quote?product=tiktok-followers&quantity=5000"

{
  "product": "tiktok-followers", "quantity": 5000, "variant_id": null,
  "unit_price_usd": "1.50", "price_unit": 1000,
  "total_usd": "7.50"
}

11إنشاء طلب

يُخصم الثمن من محفظتك ويبدأ التنفيذ فوراً — في نداء واحد.

curl -X POST https://store.72-61-87-107.nip.io/api/partner/v1/orders \
  -H "X-API-Key: axk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{
    "product": "pubg-uc-60",
    "quantity": 1,
    "reference": "SHOP-10001",
    "fields": { "player_id": "5123456789" }
  }'

{
  "reference": "AX-ORD-3F9A2B01",
  "partner_reference": "SHOP-10001",
  "status": "processing",
  "product": "pubg-uc-60", "product_name": "60 شدة",
  "quantity": 1, "unit_price_usd": "0.9152", "total_usd": "0.9152",
  "fields": { "player_id": "5123456789" },
  "delivery": "",
  "created_at": "2026-09-27T14:05:31", "completed_at": null
}

12متابعة الطلبات

طلبٌ واحد، أو دفعة مراجع، أو كل طلباتك صفحةً صفحة.

curl -H "X-API-Key: axk_YOUR_KEY" https://store.72-61-87-107.nip.io/api/partner/v1/orders/SHOP-10001

{ "reference": "AX-ORD-3F9A2B01", "partner_reference": "SHOP-10001", "status": "completed",
  ..., "delivery": "تم الشحن إلى المعرّف 5123456789", "completed_at": "2026-09-27T14:05:44" }

{
  "items": [ { "partner_reference": "SHOP-10001", "status": "completed", ... },
             { "partner_reference": "SHOP-10002", "status": "processing", ... } ],
  "missing": [ "SHOP-99999" ]
}

{ "items": [ ... ], "page": 1, "per_page": 50, "total": 318, "pages": 7 }

13دورة حياة الطلب

كل طلب ينتهي إلى إحدى حالتين: مكتمل بتسليمه، أو مُسترَد إلى محفظتك.

14الكميات والتسعير

ثلاثة أنماط للكمية — تعامل معها في متجرك كما يلي.

أ) منتج بالقطعة — price_unit = 0

الإجمالي = price_usd × quantity. بطاقة هدايا بـ"5.20" × 3 = "15.60".

ب) منتج بالوحدة المجمّعة — price_unit > 0

price_usd هو ثمن كل price_unit وحدة، والكمية يجب أن تكون من مضاعفاتها. متابعون بـ"1.50" لكل 1000: طلب 5000 = 5 × 1.50 = "7.50".

ج) كميات محدَّدة — allowed_quantities غير فارغة

تُقبل هذه القيم فقط، مثل [110, 150, 210]. اعرضها لعميلك كخيارات لا كحقل حرّ.

15منع ازدواج الطلبات

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

كل طلب يحمل reference فريداً من طرفك. إن أعدت إرسال الطلب بنفس المرجع — لانقطاع اتصال أو مهلة أو خطأ في نظامك — يُعاد إليك الطلب الأول نفسه ولا يُنشأ طلب ثانٍ ولا يُخصم مرّتين.

• استخدم مرجعاً ثابتاً لكل عملية شراء في متجرك (رقم طلب عميلك مثلاً)، لا رقماً عشوائياً عند كل محاولة.
• عند انتهاء المهلة دون رد: أعد الإرسال بنفس المرجع، أو استعلم GET /orders/{reference} — ستجد الطلب إن كان أُنشئ.
• المرجع خاصّ بحسابك: شريكٌ آخر يستخدم المرجع نفسه لا يتعارض معك.
• المرجع نفسه بمحتوى مختلف (منتج أو كمية أخرى) يعيد الطلب الأول أيضاً — لكل عملية شراء جديدة مرجع جديد.

16الأخطاء

كل خطأ يعود بصيغة واحدة ورمز ثابت — ابنِ منطقك على code لا على نص الرسالة.

HTTP/1.1 402 Payment Required

{
  "code": "insufficient_balance",
  "message": "رصيد المحفظة غير كافٍ لإتمام العملية.",
  "details": {}
}

17أمثلة كاملة

دورة كاملة: تحقّق ← طلب ← متابعة حتى النتيجة، بمعالجة صحيحة للأخطاء وإعادة المحاولة.

Python

import os, time, requests

API = "https://store.72-61-87-107.nip.io/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 input
        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(product, player_id, shop_order_id, quantity=1):
    order = call("POST", "/orders", json={
        "product": product, "quantity": quantity,
        "reference": f"SHOP-{shop_order_id}",        # fixed per purchase
        "fields": {"player_id": player_id}})
    while order["status"] in ("paid", "processing"):
        time.sleep(15)
        order = call("GET", f"/orders/{order['reference']}")
    return order                                        # completed or refunded

result = buy("pubg-uc-60", "5123456789", 10001)
print(result["status"], result["delivery"])

PHP

<?php
$api = 'https://store.72-61-87-107.nip.io/api/partner/v1';
$key = getenv('AXIS_API_KEY');

function axis($method, $path, $body = null) {
    global $api, $key;
    $ch = curl_init($api . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => ["X-API-Key: $key", 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS     => $body ? json_encode($body, JSON_UNESCAPED_UNICODE) : null,
    ]);
    $raw = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    $data = json_decode($raw, true);
    if ($status >= 400) throw new Exception($data['code'] . ': ' . $data['message']);
    return $data;
}

$order = axis('POST', '/orders', [
    'product'   => 'pubg-uc-60',
    'reference' => 'SHOP-10001',
    'fields'    => ['player_id' => '5123456789'],
]);
while (in_array($order['status'], ['paid', 'processing'])) {
    sleep(15);
    $order = axis('GET', '/orders/' . $order['reference']);
}
echo $order['status'] . PHP_EOL . $order['delivery'];

Node.js

const API = 'https://store.72-61-87-107.nip.io/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 order = await axis('POST', '/orders', {
  product: 'pubg-uc-60', reference: 'SHOP-10001', fields: { player_id: '5123456789' },
});
while (['paid', 'processing'].includes(order.status)) {
  await new Promise(r => setTimeout(r, 15000));
  order = await axis('GET', `/orders/${order.reference}`);
}
console.log(order.status, order.delivery);

18أفضل الممارسات

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

19قائمة التحقق قبل الإطلاق

راجعها بنداً بنداً قبل فتح الربط لعملائك.

20الدعم وسجل التغييرات

نحن هنا حين تحتاجنا.

• الدعم الفني: من صفحة «الدعم» في حسابك على https://store.72-61-87-107.nip.io — اذكر مرجع الطلب (AX-ORD-… أو مرجعك) وتوقيت النداء.
• مفاتيحك: https://store.72-61-87-107.nip.io/api-access
• هذه الوثيقة على الإنترنت: https://store.72-61-87-107.nip.io/developers

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

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