دليل المطوّر

هذا الدليل لمطوّر موقع الوكيل المبرمج خصيصاً (PHP أو غيرها). المطلوب رابطان يقرأ منهما ترابط المنتجات والتصنيفات كل ساعة — بلا أي كتابة على موقعك. إن كان موقعك على ووكومرس فلا تحتاج هذا الدليل: اختر «ووكومرس» في صفحة «ربط API».

1. الفكرة

تجهّز في موقعك رابطاً أساسياً (مثل https://example.com/trabt-api.php) ومفتاحاً سرياً، ويُدخلهما الوكيل في ترابط ← المنتجات ← ربط API ← «موقع خاص». بعدها يستدعي ترابط:

  • GET {API URL}/products
  • GET {API URL}/categories

كل طلب يحمل الترويسة Authorization: Bearer <المفتاح>. ارفض أي طلب بمفتاح خاطئ بالرمز 401.

2. المنتجات — GET /products

أعد قائمة 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
  }
]

3. التصنيفات — GET /categories

اختياري: إن لم يوجد يُكمل ترابط بلا تصنيفات. parent_id للتصنيف الأب أو null.

[
  { "id": 10, "name": "إلكترونيات", "parent_id": null },
  { "id": 12, "name": "سماعات", "parent_id": 10 }
]

4. كود PHP جاهز

ملف واحد بلا مكتبات. عدّل بيانات قاعدة البيانات وأسماء الجداول والأعمدة لتطابق موقعك، وضع مفتاحاً عشوائياً طويلاً.

<?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}]

5. اختبر قبل الربط

curl -H "Authorization: Bearer مفتاحك" https://example.com/trabt-api.php/products
curl -H "Authorization: Bearer مفتاحك" https://example.com/trabt-api.php/categories

يجب أن يعيد الأمر الأول قائمة المنتجات بصيغة JSON. ثم أعطِ الوكيل الرابط والمفتاح ليضغط «حفظ واختبار الربط» — تظهر له رسالة بعدد المنتجات المسحوبة أو بسبب الخطأ.

6. قواعد مهمة

  • الرابط يبدأ بـ https، ولا يُحوِّل (redirect) لعنوان آخر — ترابط لا يتبع التحويلات. استخدم الرابط النهائي بالضبط (مع www أو بدونها كما يفتح موقعك).
  • المنتج الذي يختفي من ردّ /products يُخفى عند التجّار. لإيقاف منتج مؤقتاً أعده بكمية 0 بدل حذفه.
  • أجب خلال 20 ثانية. إن كان عندك آلاف المنتجات فاجعل الاستعلام سريعاً (فهرس على الأعمدة المستخدمة).
  • لا تغيّر id المنتج: تغييره يعني منتجاً جديداً عند التاجر.
  • ترابط يقرأ فقط ولا يكتب على موقعك. الطلبات تصلك من التاجر كالمعتاد عبر الوكيل.
  • المفتاح سري: لا تضعه في كود الواجهة ولا في رابط. لتغييره عدّله في الملف ثم أدخله من جديد في «ربط API».

أسئلة؟ راسلنا على support@trabt.net