# بيكسلات التتبع

هذه النقاط الأربع تدير بيكسلات التتبع الخاصة بالمتجر، وهي القائمة نفسها التي يعدّلها التاجر في صفحة **إعدادات البكسل** بلوحة التحكم (`/dashboard/pixels`). يقبل المتجر سبعة أنواع من البيكسلات: Meta (Facebook) وTikTok وSnapchat وPinterest وGoogle Analytics وGoogle Tag Manager وGoogle Ads. ما تحتاجه كل منصة، وطريقة التأكد من وصول أحداثها، تجدهما في [دليل البيكسلات](https://dzbuild.com/ar/ar/docs/marketing/pixels.md).

الفحوص شكلية فقط. الاستجابة `201` تعني أن المعرّفات مكتوبة بصيغة صحيحة، لا أن المنصة الإعلانية قبلتها. توكن الوصول الخاص بأحداث الخادم يُكتب ولا يُقرأ: لا تُرجعه أي نقطة، والحقل `has_token` يخبرك هل يوجد توكن محفوظ.

## قبل أن تبدأ[​](#قبل-أن-تبدأ "رابط مباشر إلى قبل أن تبدأ")

* تحتاج `GET` إلى `pixels:read`. وتحتاج `POST` و`PATCH` و`DELETE` إلى `pixels:write` وإلى `Idempotency-Key` (انظر [Idempotency](https://dzbuild.com/ar/ar/api-docs/idempotency.md)). المفاتيح المُنشأة من لوحة التحكم (**الإعدادات ← واجهة API**، `/dashboard/api`) تحمل الصلاحيتين. الصلاحيات تُجمَّد لحظة إنشاء المفتاح، فالمفتاح القديم الذي تنقصه الصلاحية المطلوبة يُرجع `403 forbidden`: أنشئ مفتاحاً جديداً من لوحة التحكم.
* الخطة تحدد عدد البيكسلات التي يمكن للمتجر أن يحملها: لا شيء في الخطة المجانية، وبيكسل واحد من كل نوع في Pro، وبلا حدّ في Unlimited وEnterprise. المفتاح الشخصي لا يعمل إلا على متجر بخطة Enterprise سارية. أما التطبيق المثبّت فيصل أيضاً إلى متاجر على الخطة المجانية أو Pro، وفيها يُطبَّق الحدّ.
* يستطيع التاجر تعيين بيكسل لمنتجات أو فئات أو صفحات هبوط من لوحة التحكم. الواجهة البرمجية لا تقرأ هذه التعيينات ولا تغيّرها.

| النطاق         | الوصف                                                                     |
| -------------- | ------------------------------------------------------------------------- |
| `pixels:read`  | الاطلاع على بيكسلات التتبع الخاصة بالمتجر. توكنات الوصول لا تُرجَع أبداً. |
| `pixels:write` | إضافة بيكسلات التتبع وتعديلها وحذفها.                                     |

## كائن البيكسل[​](#كائن-البيكسل "رابط مباشر إلى كائن البيكسل")

| الحقل                      | النوع          | ملاحظات                                                                                                      |
| -------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------ |
| `id`                       | int            | رقم البيكسل في DZBuild، ويُستعمل في مسار `PATCH` و`DELETE`.                                                  |
| `pixel_type`               | string         | أحد الأنواع السبعة أسفله. يُحدَّد عند الإنشاء ولا يتغير.                                                     |
| `pixel_id`                 | string         | معرّف البيكسل أو الوسم أو القياس من المنصة الإعلانية. يُحدَّد عند الإنشاء ولا يتغير.                         |
| `pixel_name`               | string أو null | الاسم المعروض.                                                                                               |
| `has_token`                | bool           | `true` عندما يكون توكن وصول لأحداث الخادم محفوظاً.                                                           |
| `test_event_code`          | string أو null | رمز اختبار الأحداث المكتوب في لوحة التحكم. لا تستطيع الواجهة البرمجية ضبطه، و`PATCH` الذي يكتب أي حقل يمسحه. |
| `ad_account_id`            | string أو null | معرّف الحساب الإعلاني في Pinterest.                                                                          |
| `conversion_label`         | string أو null | تسمية التحويل (`conversion label`) في Google Ads.                                                            |
| `is_active`                | bool           | `false` تُبقي البيكسل وتوقف أحداثه في المتصفح وفي الخادم.                                                    |
| `is_default`               | bool           | ضبطه على `true` يلغيه من بيكسلات المتجر الأخرى من النوع نفسه. مكان تحميل البيكسل لا يتعلق به.                |
| `created_at`، `updated_at` | string         | `YYYY-MM-DD HH:MM:SS` بتوقيت الجزائر.                                                                        |

### أنواع البيكسلات[​](#أنواع-البيكسلات "رابط مباشر إلى أنواع البيكسلات")

| `pixel_type`       | المنصة             | أحداث الخادم                                        |
| ------------------ | ------------------ | --------------------------------------------------- |
| `facebook`         | Meta (Facebook)    | نعم، عندما يملك البيكسل توكن وصول.                  |
| `tiktok`           | TikTok             | نعم، عندما يملك البيكسل توكن وصول.                  |
| `snapchat`         | Snapchat           | نعم، عندما يملك البيكسل توكن وصول.                  |
| `pinterest`        | Pinterest          | نعم، عندما يملك البيكسل توكن وصول و`ad_account_id`. |
| `google_analytics` | Google Analytics   | لا.                                                 |
| `gtm`              | Google Tag Manager | لا.                                                 |
| `google_ads`       | Google Ads         | لا. الحقل `conversion_label` يُقرأ لهذا النوع فقط.  |

التوكن المرسل لنوع بلا أحداث خادم يُحفظ ولا يُستعمل أبداً.

### أين يُحمَّل البيكسل[​](#أين-يُحمَّل-البيكسل "رابط مباشر إلى أين يُحمَّل البيكسل")

البيكسل المفعّل الذي لا تعيينات له يُحمَّل في كل صفحات المتجر، بما فيها صفحات الهبوط. أما البيكسل الذي عيّنه التاجر لمنتجات أو فئات أو صفحات هبوط فلا يُحمَّل إلا في الصفحات المطابقة، وأحداث الخادم الخاصة به تتبع القاعدة نفسها. البيكسل المُنشأ عبر الواجهة البرمجية يبدأ بلا تعيينات.

## توكن الوصول[​](#توكن-الوصول "رابط مباشر إلى توكن الوصول")

`access_token` هو توكن أحداث الخادم المنسوخ من مدير الأحداث في المنصة الإعلانية. تحذف الواجهة البرمجية الأحرف غير المرئية والمسافات وعلامات الاقتباس المحيطة به، ثم ترفضه بـ `422 invalid_access_token` إذا بقي فيه `<` أو مسافة أو سطر جديد، أو إذا ساوى `pixel_id`، أو إذا كان توكن `facebook` أقصر من 40 حرفاً.

* لا تُرجع أي نقطة التوكن. ويحفظ سجلّ تعديلات المتجر القناع `••••••••` مكانه.
* مع `PATCH`، النص الفارغ أو `null` أو قيمة تحتوي ذلك القناع تُبقي التوكن المحفوظ. يمكن استبدال التوكن لكن لا يمكن إزالته عبر الواجهة البرمجية: لإزالته احذف البيكسل وأضفه من جديد بلا توكن، وهذا يزيل تعييناته أيضاً.

## `GET /v1/pixels`[​](#get-v1pixels "رابط مباشر إلى get-v1pixels")

بيكسلات المتجر من الأحدث إلى الأقدم، مع حصة الخطة في `limits`.

**المصادقة:** مفتاح منصة بصلاحية `pixels:read`.

### معاملات الاستعلام[​](#معاملات-الاستعلام "رابط مباشر إلى معاملات الاستعلام")

| المعامل      | النوع  | الافتراضي | ملاحظات                                                                                                 |
| ------------ | ------ | --------- | ------------------------------------------------------------------------------------------------------- |
| `pixel_type` | string | لا شيء    | بيكسلات هذا النوع فقط. النوع غير المعروف يُرجع قائمة فارغة.                                             |
| `limit`      | int    | 50        | من 1 إلى 200.                                                                                           |
| `cursor`     | string | لا شيء    | قيمة `next_cursor` من الصفحة السابقة. انظر [الترقيم](https://dzbuild.com/ar/ar/api-docs/pagination.md). |

### الطلب[​](#الطلب "رابط مباشر إلى الطلب")

```
curl 'https://api.dzbuild.app/v1/pixels?pixel_type=facebook' \

  -H "Authorization: Bearer $DZ_KEY"
```

### الاستجابة 200[​](#الاستجابة-200 "رابط مباشر إلى الاستجابة 200")

```
{

  "data": {

    "items": [

      {

        "id": 12,

        "pixel_type": "facebook",

        "pixel_id": "123456789012345",

        "pixel_name": "Main ad account",

        "has_token": true,

        "test_event_code": null,

        "ad_account_id": null,

        "conversion_label": null,

        "is_active": true,

        "is_default": false,

        "created_at": "2026-10-01 14:20:05",

        "updated_at": "2026-10-01 14:20:05"

      }

    ],

    "next_cursor": null,

    "has_more": false,

    "limits": {

      "plan": "enterprise",

      "can_add": true,

      "per_type_limit": null,

      "total_limit": null,

      "counts": {

        "facebook": 1,

        "tiktok": 1,

        "snapchat": 0,

        "pinterest": 0,

        "google_analytics": 1,

        "gtm": 0,

        "google_ads": 0

      },

      "total": 3

    }

  }

}
```

### `limits`[​](#limits "رابط مباشر إلى limits")

يأتي `limits` مع كل صفحة ويصف المتجر كله، مهما كان `pixel_type` الذي تصفّي به.

| الحقل            | المعنى                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `plan`           | خطة المتجر التي تأتي منها الحصة.                                                                                   |
| `can_add`        | `false` عندما لا تسمح الخطة بأي بيكسل. لا ينظر إلى الأعداد، لذا قارن `counts` بـ `per_type_limit` قبل إضافة بيكسل. |
| `per_type_limit` | عدد البيكسلات المسموح به لكل نوع، و`null` تعني بلا حدّ.                                                            |
| `total_limit`    | عدد البيكسلات المسموح به إجمالاً، و`null` تعني بلا حدّ.                                                            |
| `counts`         | عدد البيكسلات لكل نوع، بمفتاح لكل نوع من الأنواع السبعة.                                                           |
| `total`          | كل بيكسلات المتجر، المفعّلة وغير المفعّلة.                                                                         |

## `POST /v1/pixels`[​](#post-v1pixels "رابط مباشر إلى post-v1pixels")

يضيف بيكسلاً ويُرجعه مع `201`.

**المصادقة:** مفتاح منصة بصلاحية `pixels:write`. **يتطلب `Idempotency-Key`.**

### الجسم[​](#الجسم "رابط مباشر إلى الجسم")

| الحقل              | النوع  | إلزامي | ملاحظات                                                                                              |
| ------------------ | ------ | ------ | ---------------------------------------------------------------------------------------------------- |
| `pixel_type`       | string | نعم    | أحد الأنواع السبعة، بأحرف كبيرة أو صغيرة. يُقبل `type` أيضاً.                                        |
| `pixel_id`         | string | نعم    | من 1 إلى 100 حرف أو رقم أو `-` أو `_`. معرّف `facebook` من 15 إلى 17 رقماً، يُنسخ من Events Manager. |
| `pixel_name`       | string | لا     | يُقطع عند 100 حرف. يُقبل `name` أيضاً.                                                               |
| `access_token`     | string | لا     | يخضع لقواعد توكن الوصول أعلاه. اتركه أو أرسل `""` لبيكسل بلا أحداث خادم.                             |
| `ad_account_id`    | string | لا     | يُقطع عند 64 حرفاً.                                                                                  |
| `conversion_label` | string | لا     | يُقطع عند 64 حرفاً.                                                                                  |
| `is_active`        | bool   | لا     | الافتراضي `true`.                                                                                    |
| `is_default`       | bool   | لا     | الافتراضي `false`.                                                                                   |

### ما يفحصه النداء[​](#ما-يفحصه-النداء "رابط مباشر إلى ما يفحصه النداء")

تجري الفحوص بهذا الترتيب، وأول فحص يفشل هو الذي يحدد الخطأ. الرفض يُحفظ مع `Idempotency-Key` الخاص به مدة 24 ساعة: بعد إصلاح السبب، أعد إرسال النداء بـ `Idempotency-Key` جديد.

1. `pixel_type` أحد الأنواع السبعة، وإلا `422 invalid_pixel_type`.
2. `pixel_id` بالصيغة الصحيحة، وإلا `422 invalid_pixel_id`.
3. الخطة تسمح ببيكسل آخر من هذا النوع، وإلا `409 limit_reached`.
4. لا يملك المتجر بيكسلاً من النوع نفسه بـ `pixel_id` نفسه، وإلا `409 pixel_exists`.
5. `access_token`، إن أُرسل، يحترم قواعد توكن الوصول، وإلا `422 invalid_access_token`.

### الطلب[​](#الطلب-1 "رابط مباشر إلى الطلب")

```
curl -X POST 'https://api.dzbuild.app/v1/pixels' \

  -H "Authorization: Bearer $DZ_KEY" \

  -H "Content-Type: application/json" \

  -H "Idempotency-Key: pixel-meta-main-1" \

  -d '{"pixel_type": "facebook", "pixel_id": "123456789012345", "pixel_name": "Main ad account", "access_token": "EAAGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}'
```

### الاستجابة 201[​](#الاستجابة-201 "رابط مباشر إلى الاستجابة 201")

```
{

  "data": {

    "id": 12,

    "pixel_type": "facebook",

    "pixel_id": "123456789012345",

    "pixel_name": "Main ad account",

    "has_token": true,

    "test_event_code": null,

    "ad_account_id": null,

    "conversion_label": null,

    "is_active": true,

    "is_default": false,

    "created_at": "2026-10-01 14:20:05",

    "updated_at": "2026-10-01 14:20:05"

  }

}
```

## `PATCH /v1/pixels/{id}`[​](#patch-v1pixelsid "رابط مباشر إلى patch-v1pixelsid")

يغيّر الحقول التي ترسلها فقط ويُرجع البيكسل مع `200`. الجسم الفارغ لا يغيّر شيئاً.

**المصادقة:** مفتاح منصة بصلاحية `pixels:write`. **يتطلب `Idempotency-Key`.**

### الجسم[​](#الجسم-1 "رابط مباشر إلى الجسم")

| الحقل              | النوع          | ملاحظات                                                                |
| ------------------ | -------------- | ---------------------------------------------------------------------- |
| `pixel_name`       | string أو null | يُقطع عند 100 حرف. `null` أو `""` يمسحه.                               |
| `access_token`     | string         | التوكن الجديد يحل محل المحفوظ. النص الفارغ أو `null` أو القناع يُبقيه. |
| `ad_account_id`    | string أو null | يُقطع عند 64 حرفاً. `null` أو `""` يمسحه.                              |
| `conversion_label` | string أو null | يُقطع عند 64 حرفاً. `null` أو `""` يمسحه.                              |
| `is_active`        | bool           | `false` توقف البيكسل مؤقتاً وتُبقيه.                                   |
| `is_default`       | bool           | `true` تلغيه من بيكسلات المتجر الأخرى من النوع نفسه.                   |

لا يمكن إرسال `pixel_type` ولا `type` ولا `pixel_id`، حتى بقيمتها الحالية: يُرجع النداء `422 immutable_field`. لتغييرها احذف البيكسل وأضف بيكسلاً جديداً.

### الطلب[​](#الطلب-2 "رابط مباشر إلى الطلب")

```
curl -X PATCH 'https://api.dzbuild.app/v1/pixels/12' \

  -H "Authorization: Bearer $DZ_KEY" \

  -H "Content-Type: application/json" \

  -H "Idempotency-Key: pixel-12-pause-1" \

  -d '{"is_active": false}'
```

### الاستجابة 200[​](#الاستجابة-200-1 "رابط مباشر إلى الاستجابة 200")

```
{

  "data": {

    "id": 12,

    "pixel_type": "facebook",

    "pixel_id": "123456789012345",

    "pixel_name": "Main ad account",

    "has_token": true,

    "test_event_code": null,

    "ad_account_id": null,

    "conversion_label": null,

    "is_active": false,

    "is_default": false,

    "created_at": "2026-10-01 14:20:05",

    "updated_at": "2026-10-02 09:05:41"

  }

}
```

## `DELETE /v1/pixels/{id}`[​](#delete-v1pixelsid "رابط مباشر إلى delete-v1pixelsid")

يحذف البيكسل وتعييناته للمنتجات والفئات وصفحات الهبوط.

**المصادقة:** مفتاح منصة بصلاحية `pixels:write`. **يتطلب `Idempotency-Key`.**

### الطلب[​](#الطلب-3 "رابط مباشر إلى الطلب")

```
curl -X DELETE 'https://api.dzbuild.app/v1/pixels/12' \

  -H "Authorization: Bearer $DZ_KEY" \

  -H "Idempotency-Key: pixel-12-delete-1"
```

### الاستجابة 200[​](#الاستجابة-200-2 "رابط مباشر إلى الاستجابة 200")

```
{

  "data": {

    "deleted": true,

    "id": 12

  }

}
```

## التراجع[​](#التراجع "رابط مباشر إلى التراجع")

كل كتابة على البيكسلات تتم عبر الواجهة البرمجية تُسجَّل في سجلّ تعديلات المتجر. استجابة الكتابة لا تحمل رقم التغيير: ابحث عنه بـ `GET /v1/changes?entity=pixels`، الأحدث أولاً، وهي تحتاج إلى `store:read`. يتراجع `POST /v1/changes/{id}/undo` عن تغيير واحد ويحتاج إلى `pixels:write` وإلى `Idempotency-Key`. انظر [التغييرات والتراجع عنها](https://dzbuild.com/ar/ar/api-docs/resources/changes.md).

* التراجع عن تعديل يُعيد `pixel_name` و`ad_account_id` و`conversion_label` و`is_active` و`is_default`. التوكن ليس في السجل، فيبقى كما هو الآن.
* التراجع عن حذف يُعيد البيكسل بحقوله القديمة، وبرقمه `id` القديم إن بقي متاحاً، لكن بلا توكن وصول وبلا تعييناته. حدّ الخطة وفحص التكرار يبقيان ساريين، فقد يُرجع هذا التراجع `409 limit_reached` أو `409 pixel_exists`.
* لا يمكن التراجع عن إضافة بيكسل: يُرجع التراجع `422 nothing_to_restore`. احذف البيكسل بدلاً من ذلك.
* التراجع عن تعديل بيكسل حُذف بعد ذلك يُرجع `422 restore_target_missing`.
* تغييرات البيكسلات المحفوظة من لوحة التحكم لا تُسجَّل، فلا يمكن التراجع عنها عبر الواجهة البرمجية.
* لا يستطيع رمز التطبيق المثبّت قراءة التغييرات ولا التراجع عنها: كلاهما يُرجع `403 forbidden`.

## الأخطاء[​](#الأخطاء "رابط مباشر إلى الأخطاء")

| HTTP | الرمز                   | السبب                                                                                                                                                             |
| ---- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `bad_request`           | الجسم ليس JSON صالحاً، أو رقم البيكسل في المسار ليس أرقاماً فقط، أو `Idempotency-Key` غائب أو غير صالح مع `POST` أو `PATCH` أو `DELETE`.                          |
| 401  | `unauthorized`          | مفتاح خاطئ أو غائب.                                                                                                                                               |
| 402  | `quota_exceeded`        | انتهت حصة الطلبات الشهرية للمتجر. انظر [حدود المعدل](https://dzbuild.com/ar/ar/api-docs/rate-limits.md).                                                          |
| 403  | `forbidden`             | `Missing scope: pixels:read` أو `Missing scope: pixels:write`، أو `API access requires an active Enterprise plan` لمفتاح شخصي متجره ليس على خطة Enterprise سارية. |
| 404  | `not_found`             | لا يوجد بيكسل بهذا الرقم في المتجر. وبيكسل متجر آخر يُرجع الجواب نفسه.                                                                                            |
| 409  | `limit_reached`         | الخطة لا تسمح ببيكسلات أخرى من هذا النوع.                                                                                                                         |
| 409  | `pixel_exists`          | المتجر يملك من قبل بيكسلاً من هذا النوع بـ `pixel_id` نفسه.                                                                                                       |
| 413  | `payload_too_large`     | الجسم أكبر من 1 ميغابايت.                                                                                                                                         |
| 422  | `invalid_pixel_type`    | `pixel_type` غائب أو ليس أحد الأنواع السبعة.                                                                                                                      |
| 422  | `invalid_pixel_id`      | `pixel_id` غائب، أو أطول من 100 حرف، أو فيه حرف غير الحروف والأرقام و`-` و`_`، أو هو معرّف `facebook` ليس من 15 إلى 17 رقماً.                                     |
| 422  | `invalid_access_token`  | التوكن يخالف إحدى قواعد توكن الوصول.                                                                                                                              |
| 422  | `immutable_field`       | أرسل `PATCH` الحقل `pixel_type` أو `type` أو `pixel_id`.                                                                                                          |
| 422  | `pixel_write_failed`    | رُفضت الكتابة بعد نجاح الفحوص أعلاه. الرسالة تذكر السبب وقد تكون بالعربية.                                                                                        |
| 422  | `idempotency_key_reuse` | استُعمل `Idempotency-Key` نفسه مع طريقة أو مسار أو جسم مختلف.                                                                                                     |
| 429  | `rate_limited`          | طلبات كثيرة. انتظر المدة في `Retry-After`.                                                                                                                        |
| 500  | `server_error`          | فشل الطلب. أعد المحاولة بالـ `Idempotency-Key` نفسه.                                                                                                              |