language
تم الكشف تلقائياً

قمنا باختيار العربية و Saudi Riyal (﷼) لك.

وثائق B2B

B2B API – استرجاع معلومات الطلبات والمنتجات تلقائياً

تتوفر REST API الخاصة بنا لكل عميل لديه حساب عميل، وتتيح استرجاع معلومات الطلبات والمنتجات تلقائياً ودمجها في أنظمتك الخاصة.

المصادقة

تتطلب جميع طلبات API مفتاح API صالحاً يُرسَل في HTTP-Header. وصول API مرتبط بحساب العميل الخاص بك ومتاح لحسابات العملاء بشكل عام.

info لا تحتاج إلى طلب B2B منفصل: سجّل الدخول بحساب العميل الخاص بك، وافتح تبويب API وأنشئ هناك مفتاح API الخاص بك. إلى وصول API ←

تنسيق Header

HTTP Request Header
X-API-Key: YOUR_API_KEY_HERE
Content-Type: application/json
Accept: application/json

مثال باستخدام cURL

cURL
curl -X GET "https://artumos.com/api/v1/orders" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -H "Accept: application/json"

Base URL

جميع نقاط النهاية نسبية إلى Base URL التالي:

Base URL
https://artumos.com/api/v1

تُعاد جميع الاستجابات بصيغة JSON يُعاد (Content-Type: application/json).

Rate Limits

Planالطلبات / دقيقةالطلبات / يوم
حساب العميل605.000
حد موسّععند الطلبعند الطلب

عند التجاوز يُعاد HTTP 429 Too Many Requests يُعاد. وHeader Retry-After يحتوي على وقت الانتظار بالثواني.

رموز الأخطاء

HTTP-Codeالمعنى
200 OKالطلب ناجح
400 Bad Requestمعاملات غير صالحة
401 Unauthorizedمفتاح API مفقود أو غير صالح
403 Forbiddenلا توجد صلاحية لهذا المورد
404 Not Foundالمورد غير موجود
429 Too Many Requestsتم تجاوز Rate Limit
500 Internal Server Errorخطأ في الخادم – يرجى التواصل مع الدعم

تنسيق استجابة الخطأ

JSON
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}

نقطة النهاية: الطلبات

GET /api/v1/orders جميع طلبات الحساب
Parameterالنوعالوصف
pageintegerالصفحة (افتراضي: 1)
per_pageintegerعدد العناصر لكل صفحة (بحد أقصى 100)
statusstringpaid | pending | all
Beispiel-Response
{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "ORD-12345",
        "status": "paid",
        "total": 49.99,
        "currency": "EUR",
        "created_at": "2026-01-15T10:30:00Z",
        "items_count": 2
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 42
    }
  }
}
GET /api/v1/orders/{order_id} استرجاع طلب فردي

نقطة النهاية: معلومات المنتج والطلب

GET /api/v1/orders/{order_id}/codes جميع معلومات المنتج لطلب ما
Beispiel-Response
{
  "success": true,
  "data": {
    "order_id": "ORD-12345",
    "codes": [
      {
        "id": "CODE-789",
        "product_name": "Beispielprodukt vom Marktplatz",
        "product_sku": "ART-PRODUCT-001",
        "product_info": "Hinweise laut Verkäuferangaben",
        "delivery_url": "https://...",
        "delivered_at": "2026-01-15T10:31:00Z",
        "status": "active"
      }
    ]
  }
}
GET /api/v1/codes/{code_id} استرجاع معلومة منتج فردية
warning يجوز استخدام معلومات المنتج والطلب فقط في إطار الطلب المعني وبيانات البائع. قد تشكّل المشاركة التعسفية انتهاكاً لشروط الاستخدام.

نقطة النهاية: المنتجات

GET /api/v1/products استرجاع كتالوج المنتجات
Parameterالنوعالوصف
categorystringتصفية حسب slug الفئة
in_stockbooleanالمنتجات المتوفرة فقط
pageintegerالصفحة
Beispiel-Response
{
  "success": true,
  "data": {
    "products": [
      {
        "id": 42,
        "sku": "ART-PRODUCT-001",
        "name": "Beispielprodukt vom Marktplatz",
        "price": 49.99,
        "currency": "EUR",
        "in_stock": true,
        "category": "handmade"
      }
    ]
  }
}

Webhooks

تتيح Webhooks تلقّي إشعارات فورية عند توفير الطلبات أو الرموز. يمكن تسجيل عناوين Webhook-URL في حساب العميل.

الأحداث المتاحة

Eventالوصف
order.paidتم دفع الطلب
codes.deliveredتم توفير الرموز
order.refundedتم استرداد الطلب

Webhook Payload

POST – نقطة نهاية Webhook الخاصة بك
{
  "event": "codes.delivered",
  "timestamp": "2026-01-15T10:31:05Z",
  "data": {
    "order_id": "ORD-12345",
    "codes_count": 2
  },
  "signature": "sha256=..."
}

تحقق من التوقيع باستخدام Webhook-Secret الخاص بك: HMAC-SHA256(payload, webhook_secret)

الأسئلة الشائعة

من يمكنه استخدام B2B API؟

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

ما تنسيق الاستجابات؟

تُعاد جميع الاستجابات بصيغة JSON. يحتوي الكائن الجذر دائماً على success: true/false بالإضافة إلى إما data أو error.

هل يمكنني تقديم الطلبات عبر API؟

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

هل توجد بيئة Sandbox؟

نعم. يمكن تفعيل Sandbox في حساب العميل ضمن تبويب „وصول API“ وهي مرتبطة مباشرة بمفتاح API المعني.