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

هذه النقاط الأربع تدير بيكسلات التتبع الخاصة بالمتجر، وهي القائمة نفسها التي يعدّلها التاجر في صفحة إعدادات البكسل بلوحة التحكم (/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 جديد.

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.

الطلب

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 نفسه.