ما تقرؤه الـ API

تقرأ الـ API الأرقام نفسها التي تعرضها شاشات Gloriads. ولا تغيّر أبدًا حسابك ولا إعلاناتك.

نقاط النهاية

كل معامل وكل حقل موجود في مرجع API، مع زر Try it.

الفترات

تغطي /summary و/timeline و/reports/products فترة ما. أرسل واحدًا مما يلي:

• إذا لم ترسل شيئًا: last_30_days، كما في لوحة التحكم.
• يغطي range الأيام المكتملة، أي تلك التي تجمعها لوحة التحكم: last_30_days هي الأيام الثلاثون المنتهية بالأمس، وthis_month وthis_year تتوقفان عند الأمس. فـ Amazon تنسب البيع إلى نقرته بعد أيام، لذا لا يكتمل اليوم أبدًا.
• today هو اليوم، وكذلك this_month في اليوم الأول من الشهر (إذ لا يضم بعد أي يوم مكتمل).
• يبدأ all_time من أقدم يوم تحتفظ به Gloriads ويمتد حتى اليوم، مثل كامل المدة في لوحة التحكم.
• لتضمين اليوم، أرسل start_date وend_date، مع جعل end_date تاريخ اليوم.
• يحدد timezone (Europe/Paris، America/New_York…) أي يوم هو « اليوم ». والقيمة الافتراضية UTC.
• تذكر كل إجابة الأيام التي تغطيها في period.

مقارنة فترتين

أضف compare إلى /summary أو /timeline أو /reports/products، مثل مقارنة مع في لوحة التحكم:

وتضيف الإجابة comparison، وفيه أرقام الفترة المقارَن بها، وكيف تغيّر كل من الإنفاق والمبيعات وACOS ومرات الظهور والنقرات وCPC وعمليات الشراء:

"changes": {
  "spend": { "kind": "change", "percent": 18.2, "direction": "up", "tone": "neutral" },
  "acos": { "kind": "change", "percent": -6.5, "direction": "down", "tone": "good" }
}

• تنتهي الفترتان كلتاهما بالأمس، كما في لوحة التحكم: فإذا امتدت التواريخ حتى اليوم، يُحذف منها اليوم، ويذكر period ذلك.
• تعني kind: "new" أن الرقم كان صفرًا من قبل؛ وتعني kind: "none" أنه لا يوجد ما يُقارَن (ACOS بلا مبيعات).
• يذكر tone ما إذا كان التغيُّر خبرًا جيدًا، مثل ألوان لوحة التحكم. وقيمته للإنفاق neutral دائمًا.
• لا يسبق all_time أي شيء، ولا يضم today أي يوم مكتمل: فيذكر comparison السبب عندئذٍ في unavailable.
• عندما لا تحتفظ Gloriads بأي سجل للفترة المقارَن بها، تكون أرقامها null وتكون قيمة history_covered هي false.

عوامل التصفية

تُرفض القيمة غير المعروفة بالرمز 400 مع ذكر اسمها، ولا يُجاب عنها أبدًا بأصفار.

إجماليات فترة

curl "https://gloriads.com/api/v1/summary?range=last_month&marketplaces=US" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "period": { "start_date": "2026-09-01", "end_date": "2026-09-30", "range": "last_month", "timezone": "UTC" },
  "currency": "USD",
  "spend": 13140.53,
  "sales": 46562.2,
  "acos": 28.22,
  "roas": 3.54,
  "impressions": 3945723,
  "clicks": 13973,
  "ctr": 0.35,
  "average_cpc": 0.94,
  "purchases": 1479,
  "conversion_rate": 10.58,
  "by_marketplace": [ … ],
  "by_ad_product": [ … ],
  "meta": { "data_last_date": "2026-10-09", "history_covered": true, "truncated": false }
}

• acos وctr وconversion_rate نِسب مئوية: تعني 28.22 نسبة 28.22%.
• يعدّ purchases الطلبات، مثل عمليات الشراء (Purchases) في وحدة تحكم Amazon Ads، لا الوحدات.
• النسبة التي لا أساس لها (ACOS بلا مبيعات) قيمتها null، وليست 0 أبدًا.

يومًا بيوم أو شهرًا بشهر

تقبل /timeline الفترة وعوامل التصفية نفسها، وتُرجع في data نقطة لكل يوم أو لكل شهر.

• يختار granularity=auto (الافتراضي) الأيام حتى 92 يومًا، والأشهر لما يتجاوز ذلك، مثل الرسم البياني في لوحة التحكم.
• يُرفض granularity=day لأي فترة تتجاوز 92 يومًا.
• يُستبعد أي يوم بلا أرقام.

لكل منتج

تُرجع /reports/products صفًا لكل منتج معلَن عنه (ASIN)، مرتبًا حسب sort (spend افتراضيًا) وorder (desc افتراضيًا).

• يجمع product_id: null ما لا تربطه Amazon بأي منتج، وأغلبه من الماركات المدعومة.
• title هو اسم المنتج كما يرد في تقرير المنتجات من Amazon، في السوق الذي أنفق فيه أكثر خلال الفترة. وقيمته null عندما يكون product_id: null، وكذلك ما دامت Gloriads لم تتلقَّ بعد من Amazon أسماء منتجات الحساب.
• تأتي الصفوف على صفحات: راجع الحدود والأخطاء.

إعلانات البث التلفزيوني

تستبعد التقارير الأخرى إعلانات البث التلفزيوني (الإعلانات التلفزيونية على Prime Video وتطبيقات البث)، كما تفعل لوحة التحكم: إذ لا تُدرجها Amazon في التقرير الذي تأتي منه تلك التقارير. وتقرؤها /reports/streaming-tv من تقرير منفصل من Amazon، لسوق واحد.

curl "https://gloriads.com/api/v1/reports/streaming-tv?marketplace_id=3478512345678901&range=last_30_days" \
  -H "Authorization: Bearer YOUR_API_KEY"

• فترة مدتها 31 يومًا على الأكثر، ضمن آخر 95 يومًا: وهذه حدود Amazon لهذا التقرير.
• قد يُجاب أول استدعاء لفترة ما بـ "status": "pending" بينما تُعدّ Amazon التقرير، وعادةً ما يستغرق ذلك بضع دقائق. أعد الاستدعاء بعد meta.retry_after_seconds. ثم يُحتفظ بالتقرير 3 ساعات.
• تأتي كل حملة مع إنفاقها ومرات ظهورها وcpm (التكلفة لكل ألف مرة ظهور) ونقراتها ومبيعاتها وعمليات الشراء وunits_sold.
• المبالغ بعملة السوق نفسه، لا بالدولار الأمريكي (USD).
• "status": "unavailable": لا تتيح Amazon إعلانات البث التلفزيوني لهذا الحساب، كحساب مؤلف KDP مثلًا.

الحملات والمجموعات الإعلانية

تحتاج نقطتا النهاية كلتاهما إلى marketplace_id: قيمة id من /marketplaces.

curl "https://gloriads.com/api/v1/campaigns?marketplace_id=3478512345678901&states=ENABLED" \
  -H "Authorization: Bearer YOUR_API_KEY"

• تُسرد الحملات المفعّلة والمتوقفة مؤقتًا في المنتجات المدعومة والماركات المدعومة وإعلانات العرض. أما الحملات المؤرشفة فلا تُسرد أبدًا.
• الميزانيات وعروض الأسعار بعملة السوق نفسه (currency_code في /marketplaces).
• يذكر provenance ما إذا كانت Gloriads قد أنشأت الحملة، أو عدّلتها، أو لم تمسّها قط.
• يُبقي /ad-groups?campaign_id=… المجموعات الإعلانية لحملة واحدة فقط.
• حتى 1,000 صف في الصفحة (100 افتراضيًا).

الكلمات الرئيسية والأهداف والإعلانات

تسرد /targets و/ads ما يوجد داخل حملة واحدة. وتحتاج كلتاهما إلى marketplace_id وcampaign_id؛ ويُبقي ad_group_id مجموعة إعلانية واحدة من مجموعاتها.

curl "https://gloriads.com/api/v1/targets?marketplace_id=3478512345678901&campaign_id=28430987654321" \
  -H "Authorization: Bearer YOUR_API_KEY"

• تسرد /targets كل كلمة رئيسية مع match_type الخاص بها (EXACT، PHRASE، BROAD)، وأهداف المنتجات (أرقام ASIN)، والفئات، ومجموعات الاستهداف التلقائي، والكلمات الرئيسية والأهداف السلبية، مع bid وحالة كل منها. وتعني bid: null أن الهدف يستخدم عرض الأسعار الافتراضي للمجموعة الإعلانية.
• تسرد /ads كل إعلان مع المنتجات التي يعلن عنها (product_ids).
• تُقرأ من Amazon لحظة طلبك، ولا تحمل أي أرقام.
• في المنتجات المدعومة والماركات المدعومة وإعلانات العرض. أما المؤرشفة فلا تُسرد أبدًا.
• حتى 1,000 صف في الصفحة (100 افتراضيًا).

القواعد والنشاط

• تسرد /rules كل القواعد، الأحدث تعديلًا أولًا.
• تُظهر /rules/{rule_id}/runs ما فحصه كل تشغيل حديث وما غيّره. ولا تُدرج الاختبارات.
• تسرد /activity كل عملية نفّذتها Gloriads على Amazon: حملة أُنشئت أو نُسخت، ومنتجات أُضيفت، وتغييرات قاعدة ما، وتراجع عن تغيير. ويظهر تشغيل القاعدة مرة واحدة لكل سوق، بقيمة rule_run_id نفسها. ويُبقي tool=rule عمليات القواعد وحدها.
• تقرأ /activity/{operation_id} عملية واحدة: استدعِها مرارًا لمتابعة عملية لا تزال قيد التنفيذ.
• تسرد /activity/{operation_id}/lines ما فعلته العملية، سطرًا بسطر: الحملة أو المجموعة الإعلانية أو الإعلان أو الهدف، وما إذا كان قد أُنشئ أو غُيّر أو أُرشف، وكل قيمة قبل التغيير وبعده، وخطأ Amazon عندما يفشل سطر ما. وحتى 500 سطر في الصفحة: فقد يضم التشغيل الواحد لقاعدة ما 5,000 سطر.

مدى حداثة الأرقام

• إنها أرقام لوحة التحكم نفسها، تُقرأ من البيانات نفسها وبالشيفرة نفسها.
• مبالغ الأداء بالدولار الأمريكي (USD). إذ تحوّل Amazon أرقام كل سوق.
• تنسب Amazon المبيعات إلى النقرة بعد عدة أيام، لذا تظل الأيام الأخيرة من الفترة تنمو لبعض الوقت. ويذكر meta.data_last_date حتى أي يوم تصل الأرقام.
• تُقرأ الحملات من Amazon مرة كل 30 دقيقة على الأكثر لكل سوق. ويذكر meta.synced_at متى حدث ذلك. وفي أول استدعاء لسوق ما، قد تكون القائمة فارغة مع meta.syncing: true: أعد الاستدعاء بعد دقيقة.
• تُحدَّث أرقام المنتجات مرة يوميًا. والفترة التي تبدأ قبل السجل الذي تحتفظ به Gloriads تُرجع meta.history_covered: false.
• تُقرأ الكلمات الرئيسية والأهداف والإعلانات مباشرةً من Amazon، في كل استدعاء: ويذكر meta.read_at متى حدث ذلك.
• يُحتفظ بأرقام البث التلفزيوني 3 ساعات بعد أن تُعدّ Amazon تقريرها: ويذكر meta.report_ready_at متى أصبح التقرير جاهزًا.