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

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

قبل أن تبدأ

تحتاج GET إلى pixels:read. وتحتاج POST وPATCH وDELETE إلى pixels:write وإلى Idempotency-Key (انظر Idempotency). المفاتيح المُنشأة من لوحة التحكم (الإعدادات ← واجهة 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

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

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

معاملات الاستعلام

المعامل	النوع	الافتراضي	ملاحظات
`pixel_type`	string	لا شيء	بيكسلات هذا النوع فقط. النوع غير المعروف يُرجع قائمة فارغة.
`limit`	int	50	من 1 إلى 200.
`cursor`	string	لا شيء	قيمة `next_cursor` من الصفحة السابقة. انظر الترقيم.

الطلب

curl 'https://api.dzbuild.app/v1/pixels?pixel_type=facebook' \
  -H "Authorization: Bearer $DZ_KEY"

الاستجابة 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 مع كل صفحة ويصف المتجر كله، مهما كان pixel_type الذي تصفّي به.

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

POST /v1/pixels

يضيف بيكسلاً ويُرجعه مع 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 جديد.

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

الطلب

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

{
  "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}

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

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

الجسم

الحقل	النوع	ملاحظات
`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. لتغييرها احذف البيكسل وأضف بيكسلاً جديداً.

الطلب

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

{
  "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}

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

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

الطلب

curl -X DELETE 'https://api.dzbuild.app/v1/pixels/12' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Idempotency-Key: pixel-12-delete-1"

الاستجابة 200

{
  "data": {
    "deleted": true,
    "id": 12
  }
}

التراجع

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

التراجع عن تعديل يُعيد 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`	انتهت حصة الطلبات الشهرية للمتجر. انظر حدود المعدل.
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` نفسه.

المقالات ذات الصلة