# السلال

> سلال قابلة للمشاركة تُغلق الصفقة على واتساب

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

## نظرة عامة

تتيح السلال لزائر متجرك أن يجمع قائمة منتجات وينقلها إلى محادثة واتساب بكامل سياقها. السلة لقطة قصيرة العمر: تحصل على رمز من 7 أحرف، وتبقى صالحة 90 يومًا، ولا يمكن تعديلها: لتغييرها أنشئ سلة جديدة.

## كيف تسير العملية

1. يجمع زائر متجرك قائمة منتجات.
2. ينشئ متجرك سلة عبر POST /v1/carts ويحصل على رمز قصير.
3. ترسل للزائر رابطًا مثل https://<متجرك>/c/<الرمز> عبر واتساب.
4. عندما تبدأ المحادثة، يكون لدى وكيلك كامل السياق لما اختاره الزائر.

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

| الطريقة | المسار | الوصف |
| --- | --- | --- |
| `POST` | `/v1/carts` | إنشاء سلة قابلة للمشاركة |
| `GET` | `/v1/carts/:code` | استرجاع سلة برمزها |

## إنشاء سلة

أرسل من 1 إلى 50 عنصرًا، يشير كل منها إلى معرّف منتج مع qty بين 1 و99. الاستجابة هي الرمز القصير للسلة:

`POST /v1/carts`

```bash
curl -X POST "https://rest-api.tbit.app/v1/carts" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "prod_id_1",
        "qty": 2
      },
      {
        "id": "prod_id_2",
        "qty": 1
      }
    ]
  }'
```

الاستجابة:

```json
{
  "data": {
    "code": "K3F9X2A"
  }
}
```

## جلب سلة

يحوّل الرمز إلى عناصره، وكل عنصر كائن منتج كامل مع qty. السلال معزولة لكل حساب: المفتاح لا يسترجع إلا السلال التي أُنشئت لوكيله؛ وأي شيء آخر يُرجع 404:

`GET /v1/carts/K3F9X2A`

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

الاستجابة:

```json
{
  "data": {
    "code": "K3F9X2A",
    "created_at": "2024-09-01T12:00:00Z",
    "items": [
      {
        "_id": "prod_id_1",
        "kind": "product",
        "title": "طقم حفلة الديناصورات",
        "currency": "COP",
        "base_price": 95000,
        "qty": 2
      },
      {
        "_id": "prod_id_2",
        "kind": "product",
        "title": "بينياتا ديناصور",
        "currency": "COP",
        "base_price": 45000,
        "qty": 1
      }
    ]
  }
}
```

## ملاحظات

- تتكوّن الرموز من 7 أحرف.
- السلال صالحة لمدة 90 يومًا.
- السلال غير قابلة للتعديل: أنشئ سلة جديدة لتغيير العناصر.
- سلال الوكلاء الآخرين (أو الرموز غير المعروفة) تُرجع 404.