واجهة تكامل آمنة للمطورين

اربط متجرك أو تطبيقك مع NitroLoad

وثائق عملية ومباشرة للوصول إلى المنتجات، إنشاء الطلبات، متابعة حالتها، وقراءة رصيد المحفظة باستخدام مفتاح API آمن.

Public API v1

NitroLoad API

X-API-Key

Accept-Language: ar | en

Idempotency-Key

مصادقة واضحة

أرسل مفتاحك ضمن ترويسة X-API-Key في كل طلب.

حماية من التكرار

استخدم Idempotency-Key عند إنشاء الطلب لمنع الخصم المكرر.

عربي وإنجليزي

حدد اللغة المطلوبة عبر Accept-Language بقيمة ar أو en.

ابدأ خلال دقائق

المعلومات الأساسية قبل أول طلب

واجهة التكامل منفصلة عن واجهة الموقع الداخلية. استخدم المسار العام أدناه ومفتاح API صادر من حساب موثّق.

الرابط الأساسي

https://api.nitroload.net/api/public/v1

ترويسة المصادقة

X-API-Key: {prefix}.{secret}

ترويسة اللغة

Accept-Language: ar | en

نوع المحتوى

Content-Type: application/json

قواعد أساسية للتكامل

لا تضع مفتاح API داخل كود الواجهة الأمامية أو تطبيق قابل للتنزيل؛ احفظه في الخادم فقط.
تعامل مع جميع القيم المالية كسلاسل عشرية ولا تستخدم Number في JavaScript للحسابات المالية.
أعد المحاولة بنفس Idempotency-Key عند انقطاع الاتصال أثناء إنشاء الطلب.
احترم Retry-After عند استلام HTTP 429 ولا تكرر الطلب مباشرة.

وصول المطور

مفاتيح API الخاصة بحسابك

أنشئ مفاتيح منفصلة لكل متجر أو بوت، راقب آخر استخدام، وألغِ أي مفتاح لم تعد تحتاجه.

الكتالوج

قراءة المنتجات المتاحة

ابدأ بقائمة المنتجات، ثم اقرأ المنتج مباشرة قبل الشراء للتحقق من التوفر والكميات والحقول المطلوبة.

GET/products/يتطلب X-API-Key

قائمة المنتجات

يعيد قائمة مرقمة بالأسعار الخاصة بحسابك، التوفر، قيم الكمية، والحقول الديناميكية.

معاملات الاستعلام

page و page_size للتصفح
search للبحث بالاسم أو المعرّف المخصص
category لتصفية القسم
availability لإظهار المتوفر أو غير المتوفر
ordering للترتيب

أمثلة التنفيذ

curl --request GET 'https://api.nitroload.net/api/public/v1/products/?page=1&page_size=20&availability=true' \
  --header 'X-API-Key: YOUR_PREFIX.YOUR_SECRET' \
  --header 'Accept-Language: en'

مثال الاستجابة

application/json

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 42,
      "custom_id": "pubg-660-uc",
      "name": "PUBG Mobile 660 UC",
      "category": 3,
      "category_title": "Games",
      "delivers_codes": false,
      "availability": true,
      "qty_values": [1, 2, 5],
      "custom_fields": [
        {
          "id": 7,
          "key": "player_id",
          "label": "Player ID",
          "field_type": "text",
          "required": true,
          "options": [],
          "sort_order": 1
        }
      ],
      "pricing": {
        "base_price": "11.00000000",
        "final_price": "10.45000000",
        "discount_percent": "5.00",
        "has_offer": true,
        "offer_name": "Partner offer"
      }
    }
  ]
}

GET/products/{id}/يتطلب X-API-Key

تفاصيل منتج واحد

استخدم معرّف المنتج للتحقق من أحدث بياناته قبل إرسال الطلب.

حقول يجب احترامها

pricing.final_price هو السعر الخاص بالحساب عند توفره.
availability يجب أن تكون true قبل السماح بالشراء.
qty يجب أن تطابق إحدى القيم الموجودة في qty_values.
أنشئ field_values من custom_fields وأرسل مفاتيح الحقول المطلوبة.
delivers_codes يوضح ما إذا كان الطلب الناجح سيعيد أكواداً.

أمثلة التنفيذ

curl --request GET 'https://api.nitroload.net/api/public/v1/products/42/' \
  --header 'X-API-Key: YOUR_PREFIX.YOUR_SECRET' \
  --header 'Accept-Language: en'

مثال الاستجابة

application/json

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 42,
      "custom_id": "pubg-660-uc",
      "name": "PUBG Mobile 660 UC",
      "category": 3,
      "category_title": "Games",
      "delivers_codes": false,
      "availability": true,
      "qty_values": [1, 2, 5],
      "custom_fields": [
        {
          "id": 7,
          "key": "player_id",
          "label": "Player ID",
          "field_type": "text",
          "required": true,
          "options": [],
          "sort_order": 1
        }
      ],
      "pricing": {
        "base_price": "11.00000000",
        "final_price": "10.45000000",
        "discount_percent": "5.00",
        "has_offer": true,
        "offer_name": "Partner offer"
      }
    }
  ]
}

تنفيذ عملية شراء

إنشاء طلب بأمان

يُخصم المبلغ من المحفظة فور قبول الطلب، ثم تتم معالجة التسليم بشكل غير متزامن.

لماذا Idempotency-Key مهم؟

إذا انتهت مهلة الاتصال بعد الإرسال، أعد نفس الطلب بالمفتاح نفسه. سيعيد الخادم الطلب ذاته بدلاً من إنشاء طلب جديد وخصم الرصيد مرة ثانية.

Idempotency-Key

أنشئ المفتاح من رقم طلبك الداخلي أو UUID ثابت.
لا تولّد مفتاحاً جديداً عند إعادة محاولة الطلب نفسه.
احفظ uuid المعاد من NitroLoad لمتابعة الحالة.
استجابة النجاح الأولية هي HTTP 202 وليست دليلاً على اكتمال التسليم.

POST/orders/يتطلب X-API-Key

إنشاء طلب جديد

أرسل product وqty وfield_values، مع Idempotency-Key فريد لكل عملية شراء منطقية.

X-API-Key

YOUR_PREFIX.YOUR_SECRET

Idempotency-Key

your-order-9c09f6c4

Content-Type

application/json

أمثلة التنفيذ

curl --request POST 'https://api.nitroload.net/api/public/v1/orders/' \
  --header 'X-API-Key: YOUR_PREFIX.YOUR_SECRET' \
  --header 'Accept-Language: en' \
  --header 'Idempotency-Key: your-order-9c09f6c4' \
  --header 'Content-Type: application/json' \
  --data '{
  "product": 42,
  "qty": 1,
  "field_values": {
    "player_id": "123456789",
    "server": "Europe"
  }
}'

مثال الاستجابة

application/json

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "invoice_no": "NL-20260716-0042",
  "status": "pending",
  "product": 42,
  "product_name": "PUBG Mobile 660 UC",
  "qty": 1,
  "unit_price": "10.45000000",
  "total_price": "10.45000000",
  "delivered_codes": [],
  "failure_reason": "",
  "created_at": "2026-07-16T12:00:00Z",
  "updated_at": "2026-07-16T12:00:00Z"
}

المتابعة

قائمة الطلبات ومتابعة الحالة

اعرض طلبات التكامل أو تابع طلباً محدداً بواسطة uuid حتى يصل إلى حالة نهائية.

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

pending

تم قبول الطلب ووضعه في قائمة المعالجة.

processing

يجري تنفيذ الطلب لدى نظام التسليم.

success

اكتمل الطلب، وقد تظهر الأكواد في delivered_codes.

failed / provider_unreachable

فشل نهائي وتتم إعادة كامل المبلغ تلقائياً.

refunded

أُعيدت قيمة طلب مكتمل لاحقاً إلى المحفظة.

GET/orders/يتطلب X-API-Key

قائمة طلباتي

يعيد طلبات مفتاح API الحالي، ويمكن تصفيتها بحسب الحالة أو المنتج أو الفترة الزمنية.

أمثلة التنفيذ

curl --request GET 'https://api.nitroload.net/api/public/v1/orders/?status=success' \
  --header 'X-API-Key: YOUR_PREFIX.YOUR_SECRET' \
  --header 'Accept-Language: en'

مثال الاستجابة

application/json

[
  {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "invoice_no": "NL-20260716-0042",
    "status": "success",
    "product": 42,
    "product_name": "PUBG Mobile 660 UC",
    "qty": 1,
    "unit_price": "10.45000000",
    "total_price": "10.45000000",
    "delivered_codes": [],
    "failure_reason": "",
    "created_at": "2026-07-16T12:00:00Z",
    "updated_at": "2026-07-16T12:00:08Z"
  }
]

GET/orders/{uuid}/يتطلب X-API-Key

متابعة طلب واحد

استعلم كل عدة ثوانٍ أثناء pending أو processing، ثم توقف عند الحالة النهائية.

أمثلة التنفيذ

curl --request GET 'https://api.nitroload.net/api/public/v1/orders/123e4567-e89b-12d3-a456-426614174000/' \
  --header 'X-API-Key: YOUR_PREFIX.YOUR_SECRET' \
  --header 'Accept-Language: en'

مثال الاستجابة

application/json

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "invoice_no": "NL-20260716-0042",
  "status": "pending",
  "product": 42,
  "product_name": "PUBG Mobile 660 UC",
  "qty": 1,
  "unit_price": "10.45000000",
  "total_price": "10.45000000",
  "delivered_codes": [],
  "failure_reason": "",
  "created_at": "2026-07-16T12:00:00Z",
  "updated_at": "2026-07-16T12:00:00Z"
}

المحفظة

قراءة الرصيد المتاح

يعيد الرصيد الحالي القابل للإنفاق بالدولار. شحن المحفظة يتم من موقع NitroLoad وليس من واجهة التكامل العامة.

GET/balance/يتطلب X-API-Key

رصيد المحفظة

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

أمثلة التنفيذ

curl --request GET 'https://api.nitroload.net/api/public/v1/balance/' \
  --header 'X-API-Key: YOUR_PREFIX.YOUR_SECRET' \
  --header 'Accept-Language: en'

مثال الاستجابة

application/json

{
  "balance": "125.50000000",
  "currency": "USD"
}

تنسيق القيم المالية

balance وunit_price وtotal_price سلاسل عشرية بدقة تصل إلى 8 منازل. استخدم مكتبة Decimal أو BigNumber في الخادم.

"125.50000000"

معالجة موثوقة

صيغة الأخطاء والحالات المهمة

اعتمد على error.code في منطق التطبيق، وليس على نص الرسالة لأنه قابل للترجمة والتغيير.

بنية الخطأ الموحدة

application/json

{
  "error": {
    "code": "validation_error",
    "message": "The request contains invalid fields.",
    "details": {
      "qty": ["Select one of the supported quantities."],
      "player_id": ["This field is required."]
    }
  }
}

أفضل ممارسات الإنتاج

استخدم مهلة اتصال واضحة وExponential Backoff للأخطاء المؤقتة.
لا تسجل المفتاح الكامل أو الأكواد المسلّمة في سجلات عامة.
افصل مفتاح الإنتاج عن التطوير وعن كل متجر فرعي.
ألغِ المفتاح فور الشك بتسريبه ودوّر الأسرار دورياً.
راقب آخر استخدام ومعدل أخطاء 401 و429.

HTTP	error.code	المعنى	الإجراء المقترح
400	`validation_error`	كمية أو حقول غير صحيحة	اعرض أخطاء details بجانب الحقول
400	`insufficient_funds`	الرصيد غير كافٍ	اطلب من العميل شحن المحفظة
401	`invalid_api_key`	المفتاح غير صحيح أو ملغى	راجع X-API-Key أو أنشئ مفتاحاً جديداً
401	`malformed_api_key`	صيغة المفتاح غير صحيحة	أرسل المفتاح الكامل prefix.secret
404	`not_found`	المورد غير موجود أو لا يخص الحساب	اعرض حالة غير موجود
429	`throttled`	تم تجاوز معدل الطلبات	انتظر حسب Retry-After ثم أعد المحاولة
500	`error`	خطأ غير متوقع	سجّل رقم العملية وأعد المحاولة تدريجياً