B2B API – استرجاع معلومات الطلبات والمنتجات تلقائياً
تتوفر REST API الخاصة بنا لكل عميل لديه حساب عميل، وتتيح استرجاع معلومات الطلبات والمنتجات تلقائياً ودمجها في أنظمتك الخاصة.
المصادقة
تتطلب جميع طلبات API مفتاح API صالحاً يُرسَل في HTTP-Header. وصول API مرتبط بحساب العميل الخاص بك ومتاح لحسابات العملاء بشكل عام.
تنسيق Header
X-API-Key: YOUR_API_KEY_HERE Content-Type: application/json Accept: application/json
مثال باستخدام 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 التالي:
https://artumos.com/api/v1
تُعاد جميع الاستجابات بصيغة JSON يُعاد (Content-Type: application/json).
Rate Limits
| Plan | الطلبات / دقيقة | الطلبات / يوم |
|---|---|---|
| حساب العميل | 60 | 5.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 | خطأ في الخادم – يرجى التواصل مع الدعم |
تنسيق استجابة الخطأ
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key."
}
}
نقطة النهاية: الطلبات
/api/v1/orders
جميع طلبات الحساب
| Parameter | النوع | الوصف |
|---|---|---|
page | integer | الصفحة (افتراضي: 1) |
per_page | integer | عدد العناصر لكل صفحة (بحد أقصى 100) |
status | string | paid | pending | all |
{
"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
}
}
}
/api/v1/orders/{order_id}
استرجاع طلب فردي
نقطة النهاية: معلومات المنتج والطلب
/api/v1/orders/{order_id}/codes
جميع معلومات المنتج لطلب ما
{
"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"
}
]
}
}
/api/v1/codes/{code_id}
استرجاع معلومة منتج فردية
نقطة النهاية: المنتجات
/api/v1/products
استرجاع كتالوج المنتجات
| Parameter | النوع | الوصف |
|---|---|---|
category | string | تصفية حسب slug الفئة |
in_stock | boolean | المنتجات المتوفرة فقط |
page | integer | الصفحة |
{
"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
{
"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)
الأسئلة الشائعة
يمكن لأي عميل لديه حساب عميل استخدام وصول API. سجّل الدخول إلى حساب العميل الخاص بك واستخدم مفتاح API المرتبط للطلبات المصادَق عليها.
تُعاد جميع الاستجابات بصيغة JSON. يحتوي الكائن الجذر دائماً على success: true/false بالإضافة إلى إما data أو error.
في الإصدار الأول، تُستخدم API لاسترجاع الطلبات ومعلومات الطلبات والمنتجات. ستُفعَّل نقاط نهاية الطلبات للكتابة بشكل منفصل بمجرد توفّرها.
نعم. يمكن تفعيل Sandbox في حساب العميل ضمن تبويب „وصول API“ وهي مرتبطة مباشرة بمفتاح API المعني.