# المنتجات

> اقرأ كتالوج منتجاتك وابحث فيه بحثًا دلاليًا

- الصفحة: https://tbit.app/ar/docs/api/products
- عنوان URL الأساسي: `https://rest-api.tbit.app/v1`
- المصادقة: ترويسة `X-API-Key` تحمل مفتاحك في كل طلب (تقرأه الأمثلة من متغير البيئة `TBIT_API_KEY`)

## نظرة عامة

تعرض نقاط نهاية المنتجات كتالوج وكيلك: عرضه كاملًا، أو جلب منتج واحد، أو البحث فيه بحثًا دلاليًا. لا تُرجع إلا المنتجات النشطة (المنشورة): المسودات لا تُعرض أبدًا.

مفتاح قابل للنشر: في نقاط نهاية قراءة الكتالوج يعمل مفتاح API كمفتاح قابل للنشر (يعرّف حسابك ويقيس الاستخدام؛ وبيانات الكتالوج عامة). يمكنك استخدامه بأمان من كود المتصفح، تمامًا مثل المفتاح القابل للنشر في Stripe.

## نقاط النهاية

| الطريقة | المسار | الوصف |
| --- | --- | --- |
| `GET` | `/v1/products` | عرض المنتجات النشطة |
| `GET` | `/v1/products/:id` | جلب منتج واحد |
| `GET` | `/v1/products/search` | بحث دلالي في الكتالوج |

## عرض المنتجات

تُرجع قائمة مقسّمة إلى صفحات بالمنتجات النشطة. صفِّ حسب وسم الفئة أو حسب النوع:

| المعامل | النوع | الوصف |
| --- | --- | --- |
| `limit` | `number` | من 1 إلى 100، الافتراضي 50 |
| `offset` | `number` | إزاحة الصفحات، الافتراضي 0 |
| `tag` | `string` | التصفية حسب وسم الفئة |
| `kind` | `string` | 'product' أو 'service' |

`GET /v1/products`

```bash
curl "https://rest-api.tbit.app/v1/products?limit=20&tag=fiestas&kind=product" \
  -H "X-API-Key: $TBIT_API_KEY"
```

الاستجابة:

```json
{
  "data": [
    {
      "_id": "prod_id_1",
      "kind": "product",
      "title": "طقم حفلة الديناصورات",
      "description": "زينة كاملة لحفلة أطفال",
      "media": [
        { "url": "https://api.tbit.app/media/dino-kit.jpg", "alt": "طقم الحفلة", "type": "image", "position": 0 }
      ],
      "category_tags": ["حفلات", "أطفال"],
      "currency": "COP",
      "base_price": 95000,
      "compare_at_price": 120000,
      "variants": [
        {
          "id": "var_id_1",
          "title": "كبير",
          "price": 95000,
          "selected_options": [{ "name": "الحجم", "value": "كبير" }]
        }
      ],
      "created_at": "2024-09-01T12:00:00Z",
      "updated_at": "2024-09-01T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 134,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
```

## جلب منتج

اجلب منتجًا بمعرّفه. المسودات والمعرّفات غير المعروفة ومنتجات وكيل آخر تُرجع 404:

`GET /v1/products/prod_id_1`

```bash
curl "https://rest-api.tbit.app/v1/products/prod_id_1" \
  -H "X-API-Key: $TBIT_API_KEY"
```

الاستجابة:

```json
{
  "error": {
    "code": "NOT_FOUND"
  }
}
```

## البحث الدلالي

يستخدم البحث تضمينات متجهية (embeddings) وليس مطابقة الكلمات المفتاحية: استعلام مثل "حفلة ديناصورات" يجد منتجات حفلات بطابع الديناصورات حتى لو لم يحتوِ أي عنوان على هذه الكلمات حرفيًا. للبحث حد قدره 30 طلبًا في الدقيقة لكل مفتاح (إضافة إلى الحد العام البالغ 100/دقيقة). قد تتضمن كل نتيجة قيمة score للصلة:

`GET /v1/products/search`

```bash
curl "https://rest-api.tbit.app/v1/products/search?q=fiesta%20de%20dinosaurios&limit=10" \
  -H "X-API-Key: $TBIT_API_KEY"
```

الاستجابة:

```json
{
  "data": [
    {
      "_id": "prod_id_1",
      "kind": "product",
      "title": "طقم حفلة الديناصورات",
      "currency": "COP",
      "base_price": 95000,
      "score": 0.91
    }
  ]
}
```

## كائن المنتج

تُرجع كل نقاط النهاية كائنات منتج بالشكل التالي. base_price رقم بسيط بعملة الكتالوج (مثل COP، بلا وحدات فرعية). لا يظهر compare_at_price إلا عندما يكون المنتج في عرض، وهو دائمًا أكبر من base_price:

| الحقل | النوع | الوصف |
| --- | --- | --- |
| `_id` | `string` | معرّف المنتج |
| `kind` | `string` | 'product' أو 'service' |
| `title` | `string` | عنوان المنتج |
| `description` | `string` | وصف المنتج |
| `media` | `array` | مصفوفة من { url, alt?, type: 'image' \| 'video', position? } |
| `category_tags` | `string[]` | وسوم الفئات |
| `currency` | `string` | رمز العملة وفق ISO 4217 |
| `base_price` | `number` | السعر كرقم بسيط (مثل COP، بلا وحدات فرعية) |
| `compare_at_price` | `number?` | فقط عندما يكون المنتج في عرض؛ دائمًا أكبر من base_price |
| `variants` | `array` | مصفوفة من { id, title, price, compare_at_price?, selected_options: [{ name, value }] } |
| `created_at` | `string` | طابع زمني وفق ISO 8601 |
| `updated_at` | `string` | طابع زمني وفق ISO 8601 |