# واجهة برمجة تطبيقات الملخصات

يتوفر نوعان من الملخصات التي يكتبها الذكاء الاصطناعي عبر واجهة برمجة التطبيقات (API):

- **ملخصات الدردشة** — ملخص قصير لمحادثة جهة اتصال واحدة، يتم إنشاؤه عند الطلب. وهو نفس الشيء الموجود في عنصر تحكم الملخص في الدردشة (انظر [ملخص الدردشة](../chats/chat-interface.md#chat-summary)).
- **الملخصات اليومية** — ملخص شامل لمرة واحدة يومياً عبر جميع محادثاتك، وهو ما تقوم [الملخصات اليومية](../daily-summaries/daily-summaries.md) بإنشائه كل صباح: الإحصائيات، وكتلة Markdown واحدة لكل قسم، وأي مهام أنشأها الذكاء الاصطناعي منها.

- **عنوان URL الأساسي** — `https://api.dmchamp.com/v1`
- **المصادقة** — مفتاح واجهة برمجة التطبيقات الخاص بك (انظر [المصادقة](authentication.md)). يحتاج [المفتاح ذو النطاق المحدود](api-keys.md#scoped-keys) إلى قسم `Summaries`.
- **الأخطاء والترقيم** — انظر [الأخطاء والترقيم](errors-and-pagination.md)

توضح جميع الأمثلة أدناه نموذج الاستعلام `?apiKey=` في cURL ورأس `X-API-Key` في JavaScript وPython — كلاهما يعمل على كل نقطة نهاية.

---

## إنشاء ملخص دردشة

`POST /summaries` — أرسل `phoneNumber` الخاص بجهة الاتصال (مع رمز البلد) أو `email`؛ أحدهما مطلوب.

يقرأ الذكاء الاصطناعي أحدث محادثة **مغلقة** لجهة الاتصال، أو المحادثة التي لا تزال مفتوحة إذا لم يتم إغلاق أي منها بعد، ويكتب ملخصاً لها. يتم تخزين الملخص في جهة الاتصال (يظهر تحت **الملخصات** في لوحة جهة الاتصال في التطبيق) ويتم إرجاعه في الاستجابة، بحيث يمكنك إعادة توجيهه مباشرة إلى نظام إدارة علاقات العملاء (CRM)، أو قناة Slack، أو بريد إلكتروني.

**التكلفة:** نفس تكلفة رد واحد من الذكاء الاصطناعي في مستوى جودة الذكاء الاصطناعي للوكيل — Pro يكلف رصيداً واحداً، Max يكلف 0.25، Mini يكلف 0.15؛ مع ربط مفتاح Anthropic الخاص بك، تكون تكلفة Pro صفراً. يتم رفض الطلب قبل إنشاء أي شيء إذا كان الرصيد لا يغطيه.

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/summaries?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+31612345678"}'
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/summaries", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ email: "jane@example.com" }),
});
const { summary } = await res.json();
```

**Python**

```python
import requests

r = requests.post(
    "https://api.dmchamp.com/v1/summaries",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phoneNumber": "+31612345678"},
)
print(r.json()["summary"])
```

**الاستجابة**

```json
{
  "success": true,
  "message": "Chat summary generated successfully",
  "summary": "Jane asked about the 10-session package for her two children (ages 6 and 9) and preferred Saturday mornings. She booked a trial lesson for Saturday at 10:00 and wants to know whether siblings get a discount."
}
```

| الحالة | المعنى |
|---|---|
| `400` | لم يتم إرسال `phoneNumber` ولا `email`. |
| `404` | لا توجد جهة اتصال مطابقة، أو ليس لدى جهة الاتصال محادثة بعد، أو لا تحتوي المحادثة على رسائل. يوضح `message` الخاص بالنص الأساسي السبب. |
| `500` | فشل الإنشاء (على سبيل المثال، عدم كفاية الرصيد). |

> **وصفة الأتمتة: بريد إلكتروني للحجز مع ملخص.** في [أتمتة](../automations/automations.md) على مشغل **تم حجز الموعد**، أضف خطوة **طلب HTTP** التي تستدعي نقطة النهاية هذه باستخدام `${trigger.contact.phone_number}` (أو البريد الإلكتروني لجهة الاتصال)، ثم خطوة **بريد إلكتروني** تدرج `summary` من استجابة خطوة HTTP مع رابط للدردشة (عنوان تطبيقك متبوعاً بـ `/chats/` ومعرف جهة الاتصال من المشغل). يحصل فريقك على سياق الحجز في نفس البريد الإلكتروني، دون فتح صندوق الوارد.

> **قراءة الملخصات مرة أخرى.** لا توجد نقطة نهاية تسرد ملخصات الدردشة المخزنة. احتفظ بالنص من الاستجابة إذا كنت بحاجة إليه لاحقاً، أو قم بإنشائه مرة أخرى (يتم محاسبتك على كل استدعاء).

### بديل: حسب معرف جهة الاتصال

`POST /summaries/chat-summary` مع `{"contactId": "..."}` يقوم بنفس الإنشاء لجهة اتصال تمتلك معرفها بالفعل. إنه يؤكد النجاح فقط (`{"success": true, "data": "Chat summary generated successfully"}`) و**لا** يعيد النص، لذا استخدم `POST /summaries` عندما تريد الملخص نفسه. يحصل عضو الفريق الذي يقتصر مفتاحه على جهات الاتصال المخصصة له على `404` لجهة اتصال خارج هذا النطاق.

---

## الحصول على ملخص يومي

`GET /summaries/daily/{date}` — `date` هو `YYYY-MM-DD`. يعيد الملخص لذلك اليوم، أو `null` تحت `summary` عندما لم يتم إنشاء أي ملخص بعد، بالإضافة إلى تكوين القسم الخاص بك.

**cURL**

```bash
curl "https://api.dmchamp.com/v1/summaries/daily/2026-09-08?apiKey=YOUR_API_KEY"
```

**الاستجابة**

```json
{
  "success": true,
  "data": {
    "summary": {
      "date": "2026-09-08",
      "status": "completed",
      "generated_at": "2026-09-09T05:02:11.000Z",
      "stats": {
        "total_conversations": 42,
        "total_messages_sent": 310,
        "total_messages_received": 268,
        "human_alerts": 3,
        "bookings": 5,
        "new_contacts": 11,
        "sales": 2
      },
      "sections": {
        "wins_losses_improvements": "## Wins\n- ...",
        "tasks_action_items": "- Call Jane back about the sibling discount",
        "human_alerts_reviews": "...",
        "sentiment_analysis": "...",
        "booked_meetings_sales": "..."
      },
      "contact_map": { "Jane Doe": "uid_whatsapp_31612345678" },
      "auto_tasks": [],
      "created_task_ids": []
    },
    "section_configs": [
      { "id": "wins_losses_improvements", "name": "Wins, Losses & Improvements", "enabled": true, "position": 0 }
    ]
  }
}
```

- **`status`** — `pending`، `generating`، `completed` أو `failed` (مع ضبط `error`). قم باستطلاع (poll) نقطة النهاية هذه بعد إعادة التوليد حتى تقرأ `completed`.
- **`sections`** — سلسلة نصية بتنسيق markdown لكل قسم، مفهرسة بمعرف القسم. الأقسام الخمسة القياسية هي `wins_losses_improvements`، `tasks_action_items`، `human_alerts_reviews`، `sentiment_analysis` و `booked_meetings_sales`؛ الأقسام التي تضيفها تحت **Configure** في صفحة Daily Summaries تحصل على معرف `custom_…`. يتم تكرار الأسماء والترتيب في `section_configs`.
- **`contact_map`** — اسم العرض إلى معرف جهة الاتصال، حتى تتمكن من تحويل الأسماء الموجودة في النص إلى روابط.
- **`auto_tasks`** / **`created_task_ids`** — عناصر الإجراء التي استخرجها الذكاء الاصطناعي والمهام التي أنشأها منها (عندما يكون خيار **Create task cards from action items** مفعلاً).

| الحالة | المعنى |
|---|---|
| `400` | `date` ليست `YYYY-MM-DD`، أو أنها في المستقبل. |
| `403` | ميزة Daily Summaries معطلة للحساب. |

> هل تفضل الدفع (push) بدلاً من الاستطلاع (polling)؟ يقوم [حدث خطاف الويب](../integrations/webhooks.md) **Daily Summary Created** بتسليم نفس الحمولة في اللحظة التي ينتهي فيها الملخص الصباحي.

---

## إعادة توليد ملخص يومي

`POST /summaries/daily/{date}/regenerate` — يبدأ توليداً جديداً لذلك اليوم في الخلفية ويعود فوراً مع `status: "generating"` و `sections` فارغ. قم باستطلاع `GET /summaries/daily/{date}` حتى يكتمل. تنطبق نفس القواعد كما هو الحال بالنسبة لرابط **Try again** في التطبيق.

جسم اختياري `{"deleteTasks": false}` يحتفظ بالمهام التي أنشأها التشغيل السابق؛ افتراضياً يتم حذفها وإعادة إنشائها من الملخص الجديد. أرسل قيمة منطقية (boolean) حقيقية — السلسلة `"false"` يتم تجاهلها ومعاملتها كقيمة افتراضية.

```bash
curl -X POST "https://api.dmchamp.com/v1/summaries/daily/2026-09-08/regenerate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deleteTasks": false}'
```

---

## مرجع سريع

| المهمة | نقطة النهاية |
|---|---|
| توليد ملخص محادثة والحصول على النص | `POST /summaries` |
| توليد ملخص محادثة حسب معرف جهة الاتصال (لا يتم إرجاع نص) | `POST /summaries/chat-summary` |
| قراءة ملخص يوم | `GET /summaries/daily/{date}` |
| إعادة توليد ملخص يوم | `POST /summaries/daily/{date}/regenerate` |