هذا الدليل لمطوّر موقع الوكيل المبرمج خصيصاً (PHP أو غيرها). المطلوب رابطان يقرأ منهما ترابط المنتجات والتصنيفات كل ساعة — بلا أي كتابة على موقعك. إن كان موقعك على ووكومرس فلا تحتاج هذا الدليل: اختر «ووكومرس» في صفحة «ربط API».
تجهّز في موقعك رابطاً أساسياً (مثل https://example.com/trabt-api.php) ومفتاحاً سرياً، ويُدخلهما الوكيل في ترابط ← المنتجات ← ربط API ← «موقع خاص». بعدها يستدعي ترابط:
كل طلب يحمل الترويسة Authorization: Bearer <المفتاح>. ارفض أي طلب بمفتاح خاطئ بالرمز 401.
أعد قائمة JSON بكل المنتجات المتاحة للتجّار في ردّ واحد (أو داخل {"data": [...]}).
| الحقل | مطلوب | الوصف |
|---|---|---|
| id | نعم | معرّف ثابت للمنتج في موقعك (رقم أو نص). لا يتغيّر أبداً — هو ما يربط المنتج عند التاجر. |
| name | نعم | اسم المنتج كما يظهر للتاجر. |
| price | نعم | سعر الجملة للتاجر بالريال، رقم بلا عملة (مثل 85.5). |
| quantity | نعم | الكمية المتاحة، عدد صحيح. 0 = «نفدت الكمية» عند التاجر. |
| description | اختياري | وصف المنتج (نص أو HTML). |
| sku | اختياري | رمز المنتج (SKU). |
| images | اختياري | قائمة روابط صور عامة تبدأ بـ https. الأولى هي الصورة الرئيسية. |
| category_id | اختياري | معرّف التصنيف من /categories، أو null. |
[
{
"id": 1001,
"name": "سماعة لاسلكية",
"description": "<p>بطارية 30 ساعة</p>",
"price": 85.5,
"quantity": 40,
"sku": "HP-1001",
"images": ["https://example.com/img/hp-1001.jpg"],
"category_id": 12
},
{
"id": 1002,
"name": "شاحن سريع",
"price": 39,
"quantity": 0,
"images": [],
"category_id": null
}
]اختياري: إن لم يوجد يُكمل ترابط بلا تصنيفات. parent_id للتصنيف الأب أو null.
[
{ "id": 10, "name": "إلكترونيات", "parent_id": null },
{ "id": 12, "name": "سماعات", "parent_id": 10 }
]ملف واحد بلا مكتبات. عدّل بيانات قاعدة البيانات وأسماء الجداول والأعمدة لتطابق موقعك، وضع مفتاحاً عشوائياً طويلاً.
<?php
// trabt-api.php — ضع الملف في جذر موقعك، ثم أعطِ الوكيل:
// رابط API: https://example.com/trabt-api.php
// مفتاح API: قيمة TRABT_KEY أدناه
// ترابط يستدعي: {رابط API}/products و {رابط API}/categories
const TRABT_KEY = 'ضع-هنا-مفتاحاً-عشوائياً-طويلاً'; // مثال: bin2hex(random_bytes(32))
const DB_DSN = 'mysql:host=localhost;dbname=shop;charset=utf8mb4';
const DB_USER = 'shop_user';
const DB_PASS = 'shop_password';
header('Content-Type: application/json; charset=utf-8');
// 1) التحقق من المفتاح (بعض الاستضافات تمرّر الترويسة باسم مختلف)
$auth = $_SERVER['HTTP_AUTHORIZATION']
?? $_SERVER['REDIRECT_HTTP_AUTHORIZATION']
?? (function_exists('getallheaders') ? (getallheaders()['Authorization'] ?? '') : '');
if (!hash_equals('Bearer ' . TRABT_KEY, (string) $auth)) {
http_response_code(401);
echo json_encode(['error' => 'unauthorized']);
exit;
}
// 2) المسار المطلوب: /products أو /categories
$path = $_SERVER['PATH_INFO'] ?? parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$route = basename(rtrim((string) $path, '/'));
$db = new PDO(DB_DSN, DB_USER, DB_PASS, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
if ($route === 'products') {
// عدّل أسماء الجداول والأعمدة لتطابق قاعدة بيانات موقعك.
$rows = $db->query(
'SELECT id, name, description, wholesale_price, stock, sku, image_url, category_id
FROM products
WHERE is_active = 1'
)->fetchAll(PDO::FETCH_ASSOC);
$out = array_map(fn ($r) => [
'id' => (int) $r['id'],
'name' => $r['name'],
'description' => $r['description'],
'price' => (float) $r['wholesale_price'], // سعر الجملة للتاجر
'quantity' => max(0, (int) $r['stock']), // 0 = نفدت الكمية
'sku' => $r['sku'],
'images' => $r['image_url'] ? [$r['image_url']] : [],
'category_id' => $r['category_id'] !== null ? (int) $r['category_id'] : null,
], $rows);
echo json_encode($out, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
exit;
}
if ($route === 'categories') {
$rows = $db->query('SELECT id, name, parent_id FROM categories')->fetchAll(PDO::FETCH_ASSOC);
$out = array_map(fn ($r) => [
'id' => (int) $r['id'],
'name' => $r['name'],
'parent_id' => $r['parent_id'] !== null ? (int) $r['parent_id'] : null,
], $rows);
echo json_encode($out, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
exit;
}
http_response_code(404);
echo json_encode(['error' => 'not_found']);# Apache: إن وصل المفتاح فارغاً (401 دائماً) أضف هذا في .htaccess
RewriteEngine On
RewriteCond %{HTTP:Authorization} .
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]curl -H "Authorization: Bearer مفتاحك" https://example.com/trabt-api.php/products
curl -H "Authorization: Bearer مفتاحك" https://example.com/trabt-api.php/categoriesيجب أن يعيد الأمر الأول قائمة المنتجات بصيغة JSON. ثم أعطِ الوكيل الرابط والمفتاح ليضغط «حفظ واختبار الربط» — تظهر له رسالة بعدد المنتجات المسحوبة أو بسبب الخطأ.
أسئلة؟ راسلنا على support@trabt.net