Developers — AwnCare

الأعراف

عنوان أساس موحّد، وتوثيق، وغلاف استجابة ثابت عبر كل نقطة نهاية.

العنوان الأساسي

كل نقاط النهاية نسبية إلى العنوان الأساسي المُصدَّر.

text

https://awn.care/api/v1

التوثيق

وثّق باستخدام مفتاح API أُنشئ من كونسول المطورين، ويُمرَّر في ترويسة x-api-key. يعمل المفتاح بصلاحية مدير مساحة العمل.

bash

curl https://awn.care/api/v1/conversations \
  -H "x-api-key: YOUR_API_KEY"

احفظ المفاتيح سرّية

تعامل مع مفاتيح API كأنها كلمات مرور. استخدمها من كود الخادم فقط — لا تكشفها أبدًا في متصفح أو تطبيق جوال.

غلاف الاستجابة

تُغلّف الاستجابات الناجحة الحمولة في غلاف موحّد.

json

{
  "success": true,
  "data": { /* resource or array */ }
}

نقاط القوائم المُصفّحة تضيف كائن pagination.

json

{
  "success": true,
  "data": [ /* … */ ],
  "pagination": {
    "page": 1,
    "perPage": 25,
    "total": 128,
    "totalPages": 6
  }
}

تُعيد الأخطاء success: false مع رسالة مفهومة ورمز حالة HTTP مناسب.

json

{
  "success": false,
  "error": "Invalid API key"
}

التصفيح غير موحّد: معظم القوائم تستخدم page و per_page، لكن التذاكر تستخدم page و pageSize، وبعض القوائم (الأسئلة الشائعة والفئات والأقسام والردود المحفوظة) تُعيد مصفوفة مباشرة.

المحادثات

اعرض واقرأ وحدّث واحذف المحادثات، واقرأ أو أرسل الرسائل داخلها.

GET/conversations

عرض محادثات مساحة العمل، الأحدث نشاطًا أولًا. مُصفّحة.

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

الحقل	النوع	الوصف
`status`	`string`	التصفية حسب حالة المحادثة (مثل OPEN، CLOSED).
`agent_id`	`string`	التصفية حسب الوكيل المُسنَد؛ مرّر "unassigned" لغير المُسنَد.
`department_id`	`string`	التصفية حسب القسم.
`search`	`string`	مطابقة الموضوع أو اسم/بريد الزائر أو محتوى الرسائل.
`page`	`number`	رقم الصفحة (افتراضيًا 1).
`per_page`	`number`	عدد العناصر في الصفحة (افتراضيًا 25، بحد أقصى 100).

الطلب

bash

curl "https://awn.care/api/v1/conversations?status=OPEN&per_page=25" \
  -H "x-api-key: YOUR_API_KEY"

الاستجابة

json

{
  "success": true,
  "data": [
    {
      "id": "cnv_8f2a…",
      "subject": "Refund for order #1043",
      "status": "OPEN",
      "channel": "CHAT",
      "priority": "NORMAL",
      "agentId": "usr_agent_1",
      "departmentId": "dep_2",
      "lastMessageAt": "2026-07-31T09:12:44.000Z",
      "visitor": { "id": "vis_1", "name": "Sara", "email": "[email protected]", "online": true },
      "agent": { "id": "usr_agent_1", "name": "Mona", "email": "[email protected]" },
      "department": { "id": "dep_2", "nameAr": "المبيعات", "nameEn": "Sales" },
      "messages": [ { "id": "msg_9", "content": "Any update?", "type": "TEXT" } ]
    }
  ],
  "pagination": { "page": 1, "perPage": 25, "total": 128, "totalPages": 6 }
}

POST/conversations

إنشاء محادثة لزائر. يُسنَد وكيل تلقائيًا عبر محرك التوجيه عند توفره.

جسم الطلب

الحقل	النوع	الوصف
`visitorId`مطلوب	`string`	معرّف الزائر الذي تعود إليه المحادثة.
`departmentId`	`string`	قسم اختياري للتوجيه إليه.
`subject`	`string`	موضوع المحادثة (اختياري).
`channel`	`string`	قناة المنشأ (افتراضيًا CHAT).

الطلب

bash

curl -X POST https://awn.care/api/v1/conversations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "visitorId": "vis_1",
    "departmentId": "dep_2",
    "subject": "Refund for order #1043",
    "channel": "CHAT"
  }'

GET/conversations/{id}

جلب محادثة واحدة مع زائرها ووكيلها وقسمها ووسومها.

الطلب

bash

curl https://awn.care/api/v1/conversations/cnv_8f2a \
  -H "x-api-key: YOUR_API_KEY"

PATCH/conversations/{id}

تحديث حالة المحادثة أو المُسنَد إليه أو القسم أو الموضوع أو الأولوية أو البيانات الوصفية.

جسم الطلب

الحقل	النوع	الوصف
`status`	`string`	الحالة الجديدة للمحادثة.
`agentId`	`string \| null`	إسناد إلى وكيل، أو null لإلغاء الإسناد.
`departmentId`	`string \| null`	قسم اختياري للتوجيه إليه.
`subject`	`string \| null`	موضوع المحادثة (اختياري).
`priority`	`string`	أولوية المحادثة.
`metadata`	`object`	كائن بيانات وصفية حر.

الطلب

bash

curl -X PATCH https://awn.care/api/v1/conversations/cnv_8f2a \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "CLOSED", "agentId": "usr_agent_1", "priority": "HIGH" }'

DELETE/conversations/{id}

حذف مبدئي للمحادثة (نقل إلى المهملات). حذف محادثة في المهملات يزيلها نهائيًا.

الطلب

bash

curl -X DELETE https://awn.care/api/v1/conversations/cnv_8f2a \
  -H "x-api-key: YOUR_API_KEY"

الاستجابة

json

{ "success": true, "data": { "deleted": true, "permanent": false } }

GET/conversations/{id}/messages

عرض رسائل المحادثة، الأقدم أولًا. مُصفّحة.

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

الحقل	النوع	الوصف
`page`	`number`	رقم الصفحة (افتراضيًا 1).
`per_page`	`number`	عدد العناصر في الصفحة (افتراضيًا 25، بحد أقصى 100).

الطلب

bash

curl "https://awn.care/api/v1/conversations/cnv_8f2a/messages?per_page=50" \
  -H "x-api-key: YOUR_API_KEY"

POST/conversations/{id}/messages

إرسال رسالة إلى محادثة. يتطلب محتوى أو مرفقات أو نوع RICH.

جسم الطلب

الحقل	النوع	الوصف
`content`	`string`	نص الرسالة. مطلوب ما لم تُمرَّر مرفقات أو نوع RICH.
`type`	`"TEXT" \| "NOTE" \| "RICH" \| "FILE"`	نوع الرسالة. NOTE ملاحظة داخلية للوكلاء فقط.
`attachments`	`array`	مصفوفة مرفقات الملفات.
`replyToId`	`string`	معرّف الرسالة التي يرد عليها هذا.
`metadata`	`object`	كائن بيانات وصفية حر.

الطلب

bash

curl -X POST https://awn.care/api/v1/conversations/cnv_8f2a/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "تم اعتماد استرداد مبلغك.", "type": "TEXT" }'

الاستجابة

json

{
  "success": true,
  "data": {
    "id": "msg_10",
    "conversationId": "cnv_8f2a",
    "content": "تم اعتماد استرداد مبلغك.",
    "type": "TEXT",
    "userId": "api",
    "createdAt": "2026-07-31T09:20:00.000Z",
    "user": { "id": "api", "name": "API", "role": "ADMIN" }
  }
}

التذاكر

سطح تذاكر كامل: عرض، وإنشاء، وقراءة العرض الشامل، وتحديث، وتعليق.

تتطلب نقاط التذاكر وكيلًا أو مشرفًا أو مديرًا. مفاتيح API تجتاز هذا التحقق دائمًا.

GET/tickets

عرض التذاكر، الأحدث تحديثًا أولًا. ملاحظة: يستخدم page و pageSize (وليس per_page).

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

الحقل	النوع	الوصف
`status`	`string`	التصفية حسب الحالة. تُقبل قائمة مفصولة بفواصل (مثل OPEN,PENDING).
`priority`	`string`	التصفية حسب الأولوية (LOW، NORMAL، HIGH، URGENT).
`assigneeId`	`string`	التصفية حسب المُسنَد إليه؛ "me" لك، "unassigned" لغير المُسنَد.
`requesterId`	`string`	التصفية حسب معرّف مقدّم الطلب.
`q`	`string`	مطابقة نص الموضوع أو رقم التذكرة.
`page`	`number`	رقم الصفحة (افتراضيًا 1).
`pageSize`	`number`	عدد العناصر في الصفحة (افتراضيًا 25، بحد أقصى 100).

الطلب

bash

curl "https://awn.care/api/v1/tickets?status=OPEN,PENDING&priority=HIGH&page=1&pageSize=25" \
  -H "x-api-key: YOUR_API_KEY"

الاستجابة

json

{
  "success": true,
  "data": {
    "tickets": [
      {
        "id": "tkt_5",
        "number": 1043,
        "subject": "Cannot log in",
        "status": "OPEN",
        "priority": "HIGH",
        "type": "INCIDENT",
        "requester": { "id": "vis_1", "name": "Sara", "email": "[email protected]" },
        "assignee": { "id": "usr_agent_1", "name": "Mona" },
        "department": { "id": "dep_1", "nameAr": "الدعم", "nameEn": "Support" },
        "_count": { "comments": 3 }
      }
    ],
    "total": 42,
    "page": 1,
    "pageSize": 25
  }
}

POST/tickets

إنشاء تذكرة. يجب أن يكون مقدّم الطلب جهة اتصال في مساحة العمل.

جسم الطلب

الحقل	النوع	الوصف
`subject`مطلوب	`string (1–500)`	موضوع التذكرة، 1–500 حرف.
`description`مطلوب	`string`	نص التذكرة.
`requesterId`مطلوب	`string`	معرّف جهة الاتصال مقدّمة الطلب (VISITOR أو LEAD أو USER).
`priority`	`"LOW" \| "NORMAL" \| "HIGH" \| "URGENT"`	أولوية التذكرة.
`type`	`"QUESTION" \| "INCIDENT" \| "PROBLEM" \| "TASK"`	نوع التذكرة.
`departmentId`	`string \| null`	قسم اختياري للتوجيه إليه.
`assigneeId`	`string \| null`	وكيل اختياري للإسناد.
`tags`	`string[] (max 50)`	حتى 50 وسمًا حرًّا.

الطلب

bash

curl -X POST https://awn.care/api/v1/tickets \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Cannot log in",
    "description": "Getting a 500 error on sign-in since this morning.",
    "requesterId": "vis_1",
    "priority": "HIGH",
    "type": "INCIDENT",
    "tags": ["auth", "urgent"]
  }'

GET/tickets/{id}

جلب تذكرة مع تعليقاتها وأحداثها وسياق مقدّم الطلب (تذاكر ومحادثات أخرى).

الطلب

bash

curl https://awn.care/api/v1/tickets/tkt_5 \
  -H "x-api-key: YOUR_API_KEY"

الاستجابة

json

{
  "success": true,
  "data": {
    "ticket": {
      "id": "tkt_5",
      "number": 1043,
      "subject": "Cannot log in",
      "status": "OPEN",
      "priority": "HIGH",
      "requester": { "id": "vis_1", "name": "Sara", "email": "[email protected]" },
      "assignee": { "id": "usr_agent_1", "name": "Mona" },
      "comments": [ { "id": "cmt_1", "body": "Looking into it", "isInternal": false } ],
      "events": [ { "id": "evt_1", "type": "created" } ]
    },
    "requesterContext": {
      "otherTickets": [ { "id": "tkt_2", "number": 1001, "subject": "Billing" } ],
      "conversations": [ { "id": "cnv_1", "status": "CLOSED" } ]
    }
  }
}

PATCH/tickets/{id}

تحديث تذكرة. مرّر حقلًا واحدًا على الأقل. تعيين الحالة إلى SOLVED يُطلق استبيان رضا.

جسم الطلب

الحقل	النوع	الوصف
`status`	`"NEW" \| "OPEN" \| "PENDING" \| "ON_HOLD" \| "SOLVED" \| "CLOSED"`	حالة التذكرة الجديدة.
`priority`	`string`	أولوية التذكرة.
`type`	`string`	نوع التذكرة.
`assigneeId`	`string \| null`	وكيل اختياري للإسناد.
`departmentId`	`string \| null`	قسم اختياري للتوجيه إليه.
`tags`	`string[]`	حتى 50 وسمًا حرًّا.
`subject`	`string (1–500)`	موضوع التذكرة، 1–500 حرف.

الطلب

bash

curl -X PATCH https://awn.care/api/v1/tickets/tkt_5 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "SOLVED", "assigneeId": "usr_agent_1" }'

POST/tickets/{id}/comments

إضافة تعليق. الردود العامة تُرسل بريدًا للطرف الآخر؛ الملاحظات الداخلية تبقى خاصة.

جسم الطلب

الحقل	النوع	الوصف
`body`مطلوب	`string`	نص التعليق.
`isInternal`	`boolean`	عند true يكون التعليق ملاحظة داخلية (افتراضيًا false).

الطلب

bash

curl -X POST https://awn.care/api/v1/tickets/tkt_5/comments \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "We deployed a fix — please try again.", "isInternal": false }'

الاستجابة

json

{
  "success": true,
  "data": {
    "comment": { "id": "cmt_2", "body": "We deployed a fix — please try again.", "isInternal": false },
    "statusChanged": "PENDING"
  }
}

المقالات

إدارة مقالات قاعدة المعرفة (عنوان ومحتوى ثنائيا اللغة).

GET/articles

عرض المقالات، الأحدث أولًا. مُصفّحة.

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

الحقل	النوع	الوصف
`status`	`string`	التصفية حسب الحالة (مثل DRAFT، PUBLISHED).
`category_id`	`string`	التصفية حسب الفئة.
`search`	`string`	مطابقة العنوان أو المحتوى بالعربية/الإنجليزية.
`page`	`number`	رقم الصفحة (افتراضيًا 1).
`per_page`	`number`	عدد العناصر في الصفحة (افتراضيًا 25، بحد أقصى 100).

الطلب

bash

curl "https://awn.care/api/v1/articles?status=PUBLISHED&search=refund" \
  -H "x-api-key: YOUR_API_KEY"

POST/articles

إنشاء مقال. تُولَّد الروابط اللطيفة تلقائيًا من العناوين.

جسم الطلب

الحقل	النوع	الوصف
`titleAr`مطلوب	`string`	العنوان بالعربية.
`titleEn`مطلوب	`string`	العنوان بالإنجليزية.
`contentAr`	`string`	المحتوى بالعربية.
`contentEn`	`string`	المحتوى بالإنجليزية.
`categoryId`	`string`	الفئة التي يُصنَّف تحتها المقال.
`status`	`"DRAFT" \| "PUBLISHED"`	حالة النشر (افتراضيًا DRAFT).
`keywords`	`string[]`	كلمات مفتاحية للبحث.

الطلب

bash

curl -X POST https://awn.care/api/v1/articles \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "titleAr": "سياسة الاسترداد",
    "titleEn": "Refund policy",
    "contentAr": "…",
    "contentEn": "…",
    "categoryId": "cat_1",
    "status": "PUBLISHED",
    "keywords": ["refund", "returns"]
  }'

الاستجابة

json

{
  "success": true,
  "data": {
    "id": "art_7",
    "titleAr": "سياسة الاسترداد",
    "titleEn": "Refund policy",
    "slugEn": "refund-policy",
    "status": "PUBLISHED",
    "category": { "id": "cat_1", "nameEn": "Billing" }
  }
}

PATCH/articles/{id}

تحديث مقال. تغييرات المحتوى تحفظ نسخة سابقة.

الطلب

bash

curl -X PATCH https://awn.care/api/v1/articles/art_7 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "PUBLISHED" }'

DELETE/articles/{id}

حذف مقال نهائيًا.

الطلب

bash

curl -X DELETE https://awn.care/api/v1/articles/art_7 \
  -H "x-api-key: YOUR_API_KEY"

الأسئلة الشائعة

إدارة الأسئلة الشائعة ثنائية اللغة. تُعيد نقطة القائمة مصفوفة مباشرة (بدون تصفيح).

GET/faqs

عرض الأسئلة الشائعة مرتّبة حسب ترتيب الفرز.

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

الحقل	النوع	الوصف
`categoryId`	`string`	التصفية حسب (أو التصنيف تحت) فئة.
`q`	`string`	مطابقة نص السؤال أو الإجابة.

الطلب

bash

curl "https://awn.care/api/v1/faqs?categoryId=cat_1" \
  -H "x-api-key: YOUR_API_KEY"

الاستجابة

json

{
  "success": true,
  "data": [
    {
      "id": "faq_3",
      "questionEn": "How do I request a refund?",
      "answerEn": "…",
      "published": true,
      "sortOrder": 0,
      "category": { "id": "cat_1", "nameAr": "الفوترة", "nameEn": "Billing" }
    }
  ]
}

POST/faqs

إنشاء سؤال شائع. الحقول الأربعة ثنائية اللغة كلها مطلوبة.

جسم الطلب

الحقل	النوع	الوصف
`questionAr`مطلوب	`string`	السؤال بالعربية.
`questionEn`مطلوب	`string`	السؤال بالإنجليزية.
`answerAr`مطلوب	`string`	الإجابة بالعربية.
`answerEn`مطلوب	`string`	الإجابة بالإنجليزية.
`categoryId`	`string`	التصفية حسب (أو التصنيف تحت) فئة.
`published`	`boolean`	هل السؤال ظاهر (افتراضيًا true).
`sortOrder`	`number`	وزن الترتيب (افتراضيًا 0).

الطلب

bash

curl -X POST https://awn.care/api/v1/faqs \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "questionAr": "كيف أطلب استردادًا؟",
    "questionEn": "How do I request a refund?",
    "answerAr": "…",
    "answerEn": "…",
    "categoryId": "cat_1",
    "published": true,
    "sortOrder": 0
  }'

PATCH/faqs/{id}

تحديث سؤال شائع.

الطلب

bash

curl -X PATCH https://awn.care/api/v1/faqs/faq_3 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "published": false }'

DELETE/faqs/{id}

حذف سؤال شائع.

الطلب

bash

curl -X DELETE https://awn.care/api/v1/faqs/faq_3 \
  -H "x-api-key: YOUR_API_KEY"

الفئات

إدارة فئات قاعدة المعرفة. تُعيد نقطة القائمة مصفوفة مع عدد المقالات والفئات الفرعية.

GET/categories

عرض كل الفئات مرتّبة حسب ترتيب الفرز.

الطلب

bash

curl https://awn.care/api/v1/categories \
  -H "x-api-key: YOUR_API_KEY"

الاستجابة

json

{
  "success": true,
  "data": [
    {
      "id": "cat_1",
      "nameAr": "الفوترة",
      "nameEn": "Billing",
      "slugEn": "billing",
      "icon": "CreditCard",
      "sortOrder": 0,
      "_count": { "articles": 12 },
      "children": []
    }
  ]
}

POST/categories

إنشاء فئة. تُسنَد الروابط اللطيفة وترتيب الفرز تلقائيًا.

جسم الطلب

الحقل	النوع	الوصف
`nameAr`مطلوب	`string`	الاسم بالعربية.
`nameEn`مطلوب	`string`	الاسم بالإنجليزية.
`descriptionAr`	`string`	الوصف بالعربية.
`descriptionEn`	`string`	الوصف بالإنجليزية.
`icon`	`string`	اسم الأيقونة (افتراضيًا Folder).
`parentId`	`string \| null`	معرّف الفئة الأم للتداخل.
`visibility`	`string`	الظهور (افتراضيًا public).

الطلب

bash

curl -X POST https://awn.care/api/v1/categories \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nameAr": "الفوترة",
    "nameEn": "Billing",
    "icon": "CreditCard",
    "visibility": "public"
  }'

PATCH/categories/{id}

تحديث فئة.

الطلب

bash

curl -X PATCH https://awn.care/api/v1/categories/cat_1 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nameEn": "Payments", "sortOrder": 1 }'

DELETE/categories/{id}

حذف فئة. تُفكّ روابط مقالاتها ولا تُحذف.

الطلب

bash

curl -X DELETE https://awn.care/api/v1/categories/cat_1 \
  -H "x-api-key: YOUR_API_KEY"

الأقسام

إدارة أقسام التوجيه. تُعيد نقطة القائمة مصفوفة مباشرة.

GET/departments

عرض كل الأقسام، الأقدم أولًا.

الطلب

bash

curl https://awn.care/api/v1/departments \
  -H "x-api-key: YOUR_API_KEY"

الاستجابة

json

{
  "success": true,
  "data": [
    {
      "id": "dep_2",
      "nameAr": "المبيعات",
      "nameEn": "Sales",
      "isDefault": false,
      "isOnline": true,
      "priority": 0,
      "skills": []
    }
  ]
}

POST/departments

إنشاء قسم.

جسم الطلب

الحقل	النوع	الوصف
`nameAr`مطلوب	`string`	الاسم بالعربية.
`nameEn`مطلوب	`string`	الاسم بالإنجليزية.
`description`	`string`	وصف اختياري.
`isDefault`	`boolean`	اجعل هذا القسم الافتراضي (يلغي افتراضية غيره).
`isOnline`	`boolean`	هل يستقبل القسم المحادثات (افتراضيًا true).
`priority`	`number`	وزن أولوية التوجيه (افتراضيًا 0).
`skills`	`string[]`	وسوم المهارات المستخدمة في التوجيه بالمهارات.

الطلب

bash

curl -X POST https://awn.care/api/v1/departments \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nameAr": "المبيعات",
    "nameEn": "Sales",
    "isOnline": true,
    "priority": 0
  }'

PATCH/departments/{id}

تحديث قسم.

الطلب

bash

curl -X PATCH https://awn.care/api/v1/departments/dep_2 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "isOnline": false }'

DELETE/departments/{id}

حذف قسم. لا يمكن حذف القسم الافتراضي.

الطلب

bash

curl -X DELETE https://awn.care/api/v1/departments/dep_2 \
  -H "x-api-key: YOUR_API_KEY"

الردود المحفوظة

إدارة الردود الجاهزة (الماكرو) المفتاحية باختصار. تُعيد نقطة القائمة مصفوفة مباشرة.

GET/saved-replies

عرض الردود المحفوظة، الأحدث أولًا.

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

الحقل	النوع	الوصف
`search`	`string`	مطابقة الاختصار أو العنوان.

الطلب

bash

curl "https://awn.care/api/v1/saved-replies?search=refund" \
  -H "x-api-key: YOUR_API_KEY"

الاستجابة

json

{
  "success": true,
  "data": [
    {
      "id": "sr_4",
      "shortcut": "/refund",
      "titleEn": "Refund approved",
      "contentAr": "تمت الموافقة على الاسترداد.",
      "contentEn": "Your refund has been approved."
    }
  ]
}

POST/saved-replies

إنشاء رد محفوظ. يجب أن يكون الاختصار فريدًا في مساحة العمل.

جسم الطلب

الحقل	النوع	الوصف
`shortcut`مطلوب	`string`	اختصار التفعيل، مثل ‎/refund. يجب أن يكون فريدًا.
`titleAr`	`string`	العنوان بالعربية (افتراضيًا الاختصار).
`titleEn`	`string`	العنوان بالإنجليزية (افتراضيًا الاختصار).
`contentAr`مطلوب	`string`	نص الرد بالعربية.
`contentEn`مطلوب	`string`	نص الرد بالإنجليزية.

الطلب

bash

curl -X POST https://awn.care/api/v1/saved-replies \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shortcut": "/refund",
    "titleEn": "Refund approved",
    "contentAr": "تمت الموافقة على الاسترداد.",
    "contentEn": "Your refund has been approved."
  }'

PATCH/saved-replies/{id}

تحديث رد محفوظ.

الطلب

bash

curl -X PATCH https://awn.care/api/v1/saved-replies/sr_4 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contentEn": "Your refund is on its way." }'

DELETE/saved-replies/{id}

حذف رد محفوظ.

الطلب

bash

curl -X DELETE https://awn.care/api/v1/saved-replies/sr_4 \
  -H "x-api-key: YOUR_API_KEY"

إدارة الويبهوك

أنشئ وأدِر نقاط الويبهوك برمجيًا. راجع دليل الويبهوك للتسليم والتوقيع وإعادة المحاولة.

لكتالوج الأحداث وشكل الغلاف والتحقق من التوقيع، راجع دليل الويبهوك.

GET/webhooks

عرض نقاط الويبهوك. الأسرار مُقنّعة. مُصفّحة.

الطلب

bash

curl https://awn.care/api/v1/webhooks \
  -H "x-api-key: YOUR_API_KEY"

POST/webhooks

إنشاء نقطة. يُعاد سر التوقيع الكامل مرة واحدة فقط — احفظه الآن.

جسم الطلب

الحقل	النوع	الوصف
`url`مطلوب	`string (https)`	عنوان HTTPS للنقطة (يُسمح بـ http لـ localhost فقط).
`events`مطلوب	`string[]`	مصفوفة غير فارغة بأسماء الأحداث للاشتراك فيها.
`description`	`string`	تسمية اختيارية للنقطة.

الطلب

bash

curl -X POST https://awn.care/api/v1/webhooks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/awncare",
    "events": ["ticket.created", "message.created"],
    "description": "Prod ticket sync"
  }'

الاستجابة

json

{
  "success": true,
  "data": {
    "id": "whk_1",
    "url": "https://example.com/hooks/awncare",
    "events": ["ticket.created", "message.created"],
    "description": "Prod ticket sync",
    "active": true,
    "failCount": 0,
    "secret": "whsec_9c1f…full-secret-shown-once…",
    "createdAt": "2026-07-31T09:00:00.000Z"
  }
}

GET/webhooks/{id}

جلب نقطة (السر مُقنّع).

الطلب

bash

curl https://awn.care/api/v1/webhooks/whk_1 \
  -H "x-api-key: YOUR_API_KEY"

PATCH/webhooks/{id}

تحديث عنوان النقطة أو أحداثها أو حالة التفعيل أو الوصف.

جسم الطلب

الحقل	النوع	الوصف
`url`	`string (https)`	عنوان HTTPS للنقطة (يُسمح بـ http لـ localhost فقط).
`events`	`string[]`	مصفوفة غير فارغة بأسماء الأحداث للاشتراك فيها.
`active`	`boolean`	تفعيل أو تعطيل النقطة. إعادة التفعيل تصفّر عدّاد الإخفاق.
`description`	`string \| null`	تسمية اختيارية للنقطة.

الطلب

bash

curl -X PATCH https://awn.care/api/v1/webhooks/whk_1 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

DELETE/webhooks/{id}

حذف نقطة.

الطلب

bash

curl -X DELETE https://awn.care/api/v1/webhooks/whk_1 \
  -H "x-api-key: YOUR_API_KEY"

POST/webhooks/{id}/test

إرسال ping حي إلى النقطة. لا يؤثر في عدّاد إخفاقها.

الطلب

bash

curl -X POST https://awn.care/api/v1/webhooks/whk_1/test \
  -H "x-api-key: YOUR_API_KEY"

GET/webhooks/{id}/deliveries

عرض آخر 50 محاولة تسليم لنقطة.

الطلب

bash

curl https://awn.care/api/v1/webhooks/whk_1/deliveries \
  -H "x-api-key: YOUR_API_KEY"

الاستجابة

json

{
  "success": true,
  "data": [
    {
      "id": "dlv_20",
      "event": "ticket.created",
      "status": "success",
      "attempts": 1,
      "responseCode": 200,
      "error": null,
      "nextRetryAt": null,
      "createdAt": "2026-07-31T09:01:00.000Z",
      "deliveredAt": "2026-07-31T09:01:00.420Z"
    }
  ]
}

التقارير

ملخص تحليلي للقراءة فقط ضمن نطاق زمني.

GET/reports

إرجاع مقاييس إجمالية — الأحجام، وأزمنة الاستجابة والحل، والتوزيعات، وأفضل الوكلاء، والسلاسل الزمنية.

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

الحقل	النوع	الوصف
`range`	`number (days)`	عدد الأيام السابقة المشمولة (افتراضيًا 7).
`from`	`ISO date`	تاريخ البداية (ISO). استخدمه مع 'to' بدل range.
`to`	`ISO date`	تاريخ النهاية (ISO)، شاملًا اليوم كاملًا.

الطلب

bash

curl "https://awn.care/api/v1/reports?range=7" \
  -H "x-api-key: YOUR_API_KEY"

الاستجابة

json

{
  "success": true,
  "data": {
    "totalConversations": 1280,
    "conversationsInRange": 214,
    "messagesInRange": 3120,
    "avgFirstResponseMs": 48000,
    "avgResolutionMs": 5400000,
    "resolutionRate": 0.86,
    "statusBreakdown": { "OPEN": 42, "CLOSED": 172 },
    "channelBreakdown": [ { "channel": "CHAT", "count": 180 } ],
    "topAgents": [ { "id": "usr_agent_1", "name": "Mona", "conversations": 64 } ],
    "conversationsByDay": [ { "date": "2026-07-25", "count": 31 } ]
  }
}

الزوار

قراءة وتحديث ملفات الزوار (جهات الاتصال).

لا توجد نقطة عرض قائمة أو إنشاء للزوار، ولا حذف — فقط الجلب والتحديث بالمعرّف.

GET/visitors/{id}

جلب ملف زائر مع الوسوم وعدد المحادثات/الرسائل.

الطلب

bash

curl https://awn.care/api/v1/visitors/vis_1 \
  -H "x-api-key: YOUR_API_KEY"

الاستجابة

json

{
  "success": true,
  "data": {
    "id": "vis_1",
    "name": "Sara Al-Otaibi",
    "email": "[email protected]",
    "role": "LEAD",
    "online": false,
    "metadata": { "company": "Acme", "visitCount": 4 }
  }
}

PATCH/visitors/{id}

تحديث زائر. تغييرات الدور ترقية فقط (VISITOR ← LEAD ← USER). تُدمج حقول الاتصال في البيانات الوصفية.

جسم الطلب

الحقل	النوع	الوصف
`name`	`string \| null`	الاسم المعروض، أو null لمسحه.
`email`	`string \| null`	البريد الإلكتروني، أو null لمسحه.
`phone`	`string`	رقم الهاتف (يُحفظ في البيانات الوصفية).
`company`	`string`	اسم الشركة (يُحفظ في البيانات الوصفية).
`role`	`"LEAD" \| "USER"`	ترقية جهة الاتصال (VISITOR ← LEAD ← USER).
`score`	`number`	درجة العميل المحتمل (عدد صحيح).

الطلب

bash

curl -X PATCH https://awn.care/api/v1/visitors/vis_1 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sara Al-Otaibi", "company": "Acme", "score": 80 }'