واجهة التقارير

التقارير

GET /reports/{report} يقدّم التقارير الجاهزة. الزمن بـ from/to أو last (من 1 إلى 366 يومًا، أو all)؛ والمقارنة بـ compare (none، previous_period، previous_year)؛ والتجميع بـ grain؛ والترشيح بـ filter[]=dimension:value؛ والترتيب بـ sort=-measure.

أسماء التقارير:

• overview
• products
• variants
• categories
• brands
• not_selling
• customers
• cohorts
• top_customers
• customer_groups
• fulfilment
• late_orders
• payments
• tax
• funnel
• searches

مُنشئ التقارير

POST /builder/run يجيب عن سؤال مخصص: مقاييس، وأبعاد حتى ثلاثة، ومرشِّحات. وبدل بتر نتيجة كبرت أكثر من اللازم، يرفض فوق 5,000 صف بـ over_row_limit ويقترح تصديرًا.

{
  "measures": ["net_sales", "orders"],
  "dimensions": ["category"],
  "filters": [
    { "dimension": "brand", "op": "in", "values": ["…"] }
  ],
  "last": 30
}

الصلاحيات

القراءة مضبوطة بصلاحية لكل مجال — insights.sales.view وinsights.products.view وinsights.customers.view وinsights.fulfilment.view وinsights.finance.view وinsights.behaviour.view — وكل منها مقيَّد أيضًا باستحقاقات الخطة. التقارير المحفوظة والجدولة تحتاج insights.reports.manage، والمُنشئ insights.builder.use، والإعدادات insights.settings.manage. وجلسة الدعم تقرأ فقط: كل كتابة تُجاب بـ 403 support_read_only.

الرفض يتكلم اللغتين

حين ترفض الخدمة طلبًا — صلاحية غائبة، أو خطة بلا استحقاق، أو نتيجة فوق حدّ الصفوف — يحمل الرفض رمزًا للآلة مع message_ar وmessage_en، وغالبًا suggestion لما يمكن فعله بدلًا منه.

التقارير

• GET/measuresالمقاييس المتاحة في التقارير
• GET/statusحداثة البيانات والمنطقة الزمنية والعملة والمصادر
• GET/reports/{report}أحد التقارير الجاهزة
• GET/dimensions/{dimension}/valuesقيم بُعد قابل للترشيح
• POST/builder/runتشغيل تقرير مخصص

التقارير المحفوظة والجدولة

• GET/saved-reportsقائمة التقارير المحفوظة
• POST/saved-reportsحفظ تقرير
• PATCH/saved-reports/{id}تعديل تقرير محفوظ
• DELETE/saved-reports/{id}حذف تقرير محفوظ
• GET/schedulesقائمة جداول الإرسال
• POST/schedulesجدولة إرسال تقرير
• PATCH/schedules/{id}تعديل جدول
• DELETE/schedules/{id}حذف جدول
• GET/schedules/{id}/deliveriesما أرسله الجدول

التصدير والإعدادات

• POST/exportsبدء تصدير
• GET/exports/{id}حالة التصدير
• GET/exports/{id}/fileتنزيل الملف الجاهز
• GET/settingsإعدادات التقارير
• PATCH/settingsتعديل إعدادات التقارير