# POSTEX CRM API Reference

آخر تحديث: 2026-06-08

هذا الملف هو مرجع الربط الخارجي للنظام، خصوصا عند الربط مع MEGA أو أي نظام شحن/ERP آخر.

## 1. الروابط الأساسية

### واجهة الموقع

```text
https://postex-egypt.tech
```

### API المحلي داخل الموقع

```text
https://postex-egypt.tech/api
```

### WhatsApp API عبر بروكسي الموقع

استخدم هذا المسار من المتصفح أو من صفحات CRM بعد تسجيل الدخول:

```text
https://postex-egypt.tech/api/wa-proxy.php/api
```

مثال:

```text
GET https://postex-egypt.tech/api/wa-proxy.php/api/complaints
```

### API مخصص لربط MEGA بالشحنات

هذا هو المسار المفضل لأي نظام خارجي يريد قراءة أو إضافة إشارات شحنات من رسائل واتساب:

```text
https://postex-egypt.tech/api/mega-shipping.php
```

### API مخصص لربط MEGA/Postex بشحنات شركة الشحن

هذا المسار مبني على ملف العميل `APIs Documentation.pdf`، ويستخدم لإضافة الشحنات وجلب الحالة والتكلفة من Postex بدون كشف بيانات الدخول في الواجهة:

```text
https://postex-egypt.tech/api/mega-postex.php
```

## 2. شكل الرد العام

معظم endpoints ترجع JSON بالشكل التالي:

```json
{
  "success": true,
  "data": {}
}
```

وفي حالة الخطأ:

```json
{
  "success": false,
  "data": "Error message"
}
```

بعض endpoints في باك إند الواتساب ترجع:

```json
{
  "success": false,
  "error": "Error message"
}
```

## 3. التوثيق والصلاحيات

### APIs داخل CRM

تعتمد على جلسة تسجيل الدخول PHP Session.

استخدم:

```http
POST /api/auth.php
Content-Type: application/json

{
  "action": "login",
  "username": "admin",
  "password": "password"
}
```

بعد تسجيل الدخول، المتصفح يحتفظ بالجلسة ويستطيع استدعاء باقي APIs.

### APIs الخاصة بميجا

تستخدم API Key وليس Session.

يدعم النظام أي طريقة من الطرق التالية:

```http
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
```

أو:

```http
X-Mega-Api-Key: <MEGA_SHIPPING_API_KEY>
```

أو:

```http
X-API-Key: <MEGA_SHIPPING_API_KEY>
```

مكان المفتاح الحقيقي:

```text
api/config.php
MEGA_SHIPPING_API_KEY
```

مهم: لا يتم إرسال رسائل واتساب جماعية من endpoint ميجا. الربط الحالي قراءة/تسجيل فقط حتى لا يعرض أرقام الواتساب للحظر.

### بيانات دخول Postex/Mega

ملف `api/mega-postex.php` لا يستقبل `user` و `password` من الواجهة. يتم حفظهم على السيرفر فقط من خلال constants أو environment variables:

```text
MEGA_POSTEX_API_USER
MEGA_POSTEX_API_PASSWORD
MEGA_POSTEX_API_URL
```

القيمة الافتراضية للرابط:

```text
https://postex-eg.com/api/shipment.php
```

## 4. MEGA Shipping Integration

### 4.1 Health Check

```http
GET /api/mega-shipping.php?action=health
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
```

مثال curl:

```bash
curl -s "https://postex-egypt.tech/api/mega-shipping.php?action=health" \
  -H "Authorization: Bearer <MEGA_SHIPPING_API_KEY>"
```

رد متوقع:

```json
{
  "success": true,
  "data": {
    "service": "MEGA Shipping WhatsApp API",
    "version": "1.0",
    "actions": {
      "mentions": "GET shipment WhatsApp mentions by waybill",
      "ingest": "POST a shipment mention manually"
    }
  }
}
```

### 4.2 جلب رسائل واتساب مرتبطة بكود شحنة

يستخدم عندما يكون عندك كود شحنة في MEGA وتريد عرض كل رسائل واتساب الخاصة به داخل صفحة الشحنة.

```http
GET /api/mega-shipping.php?action=mentions&waybill=PTX12345678
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
```

Query params:

| الاسم | مطلوب | مثال | الوصف |
|---|---:|---|---|
| `action` | نعم | `mentions` | نوع العملية |
| `waybill` أو `code` | نعم | `PTX12345678` | كود البوليصة |
| `limit` | لا | `100` | من 1 إلى 300 |
| `phone` | لا | `201001234567` | فلترة برقم عميل/مرسل |
| `include_groups` | لا | `1` | افتراضيًا private فقط. استخدم 1 لإظهار رسائل الجروبات |

مثال:

```bash
curl -s "https://postex-egypt.tech/api/mega-shipping.php?action=mentions&waybill=PTX12345678&include_groups=1&limit=50" \
  -H "Authorization: Bearer <MEGA_SHIPPING_API_KEY>"
```

رد متوقع:

```json
{
  "success": true,
  "data": {
    "waybill": "PTX12345678",
    "count": 2,
    "latest": {
      "id": 10,
      "waybill": "PTX12345678",
      "session_id": "wa_user_21",
      "phone": "201001234567",
      "contact_name": "Customer Name",
      "direction": "in",
      "message": "مشكلة في PTX12345678",
      "msg_type": "text",
      "media_url": null,
      "wa_msg_id": "ABC",
      "source": "private",
      "group_jid": null,
      "group_name": null,
      "status": "new",
      "created_at": "2026-06-08 10:00:00"
    },
    "mentions": []
  }
}
```

### 4.3 تسجيل رسالة مرتبطة بشحنة يدويا

يستخدم لو MEGA أو أي نظام خارجي يريد إدخال رسالة في أرشيف الشحنة.

```http
POST /api/mega-shipping.php?action=ingest
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
Content-Type: application/json

{
  "waybill": "PTX12345678",
  "message": "العميل بيسأل عن الشحنة PTX12345678",
  "phone": "201001234567",
  "contact_name": "Customer Name",
  "direction": "in",
  "session_id": "mega",
  "wa_msg_id": "external-message-id",
  "msg_type": "text",
  "media_url": ""
}
```

ملاحظات:

- يمكن عدم إرسال `waybill` لو الرسالة نفسها فيها كود PTX واضح.
- `direction` تكون `in` أو `out`.
- هذا endpoint لا يرسل واتساب، فقط يسجل حركة داخل النظام.

## 5. MEGA/Postex Shipping API من ملف العميل

هذا القسم مأخوذ من ملف:

```text
/Users/akrammostafa/Desktop/new/APIs Documentation.pdf
```

مسار الربط داخل CRM:

```text
https://postex-egypt.tech/api/mega-postex.php
```

كل النداءات التالية تستخدم نفس مفتاح ميجا:

```http
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
```

### 5.1 Health Check

```http
GET /api/mega-postex.php?action=health
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
```

يرجع حالة الملف وهل بيانات Postex متسجلة على السيرفر أم لا.

### 5.2 جلب المناطق والفروع

```http
GET /api/mega-postex.php?action=get_sectors
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
```

يعادل في ملف Postex:

```text
POST https://postex-eg.com/api/shipment.php?action=getAllSectors
```

الرد يحتوي على:

| الحقل | المعنى |
|---|---|
| `id` | رقم المنطقة/القطاع |
| `name` | اسم المنطقة |
| `key_words` | كلمات بحث مرتبطة بالمنطقة |
| `gov_id` | رقم المحافظة |
| `gov_name` | اسم المحافظة |

### 5.3 إضافة شحنات مجمعة

```http
POST /api/mega-postex.php?action=add_bulk_shipments
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
Content-Type: application/json

{
  "shipments": [
    {
      "sector_id": "100",
      "keyword": "المعادي",
      "product_name": "Product Name",
      "product_desc": "Product Description",
      "phone_1": "01000000011",
      "phone_2": "01000000022",
      "service_type": 1,
      "price": 300,
      "weight": "5 kg",
      "address": "Full Address",
      "notes": "Additional notes",
      "client_name": "Client Name",
      "order_id": "12345",
      "email": "client@example.com",
      "client_id": 1,
      "quantity": "2"
    }
  ]
}
```

يعادل في ملف Postex:

```text
POST https://postex-eg.com/api/shipment.php?action=addBulkShipments
```

قواعد مهمة:

- الحد الأقصى `1000` شحنة في الطلب الواحد.
- لا يتم إرسال `user` و `password` داخل كل شحنة؛ النظام يضيفهم من إعدادات السيرفر.
- الحقول المطلوبة حسب ملف العميل: `phone_1`, `service_type`, `price`, `address`, `client_name`.
- `sector_id` يفضل إرساله إذا كان معروفًا، ويمكن استخدام `keyword` عند عدم معرفة المنطقة.

قيم `service_type`:

| القيمة | المعنى |
|---:|---|
| `1` | تسليم وتحصيل |
| `2` | شحنة استبدال |
| `3` | استرجاع طرد |

رد متوقع من Postex:

```json
{
  "response": [
    {
      "waybill": "WY154830",
      "id": "52",
      "qr_code": "52-WY154830--...",
      "order_id": "12345",
      "sector_store_name": "فرع المهندسين"
    }
  ]
}
```

### 5.4 تاريخ حالة شحنة

```http
POST /api/mega-postex.php?action=status_history
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
Content-Type: application/json

{
  "waybill": "PTX12345678"
}
```

يعادل:

```text
POST https://postex-eg.com/api/shipment.php?action=statusHistory
```

الرد يحتوي على تاريخ الحركات:

| الحقل | المعنى |
|---|---|
| `waybill` | رقم البوليصة |
| `date_created` | تاريخ الحركة |
| `status_ar` | الحالة عربي |
| `status_en` | الحالة إنجليزي |
| `reason_ar` / `reason_en` | سبب الحالة |
| `scheduled_date` | تاريخ التأجيل إن وجد |

### 5.5 الحالة الحالية لمجموعة شحنات

```http
POST /api/mega-postex.php?action=current_status
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
Content-Type: application/json

{
  "waybill": ["PTX12345678", "PTX87654321"]
}
```

يعادل:

```text
POST https://postex-eg.com/api/shipment.php?action=getCurrentStatus
```

قواعد مهمة:

- الحد الأقصى `50` بوليصة في الطلب الواحد.
- يمكن إرسال `waybill` كقيمة واحدة أو array.

### 5.6 تكلفة التوصيل لمنطقة محددة

```http
POST /api/mega-postex.php?action=delivery_cost
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
Content-Type: application/json

{
  "sector_id": "100"
}
```

يعادل:

```text
POST https://postex-eg.com/api/shipment.php?action=getDeliveryCost
```

### 5.7 كل تكاليف التوصيل

```http
GET /api/mega-postex.php?action=all_delivery_costs
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
```

يعادل:

```text
POST https://postex-eg.com/api/shipment.php?action=getAllDeliveryCost
```

### 5.8 أكواد الحالات المهمة

| الكود | الحالة |
|---:|---|
| `1` | طلب بيك اب |
| `2` | تم استلام البيك اب |
| `3` | تم الاستلام في المخزن |
| `4` | قيد التوصيل |
| `5` | تسليم ناجح |
| `6` | شحنة مؤجلة |
| `7` | تم الارتجاع للمخزن |
| `8` | تقفيل المرتجع |
| `13` | فشل التسليم |
| `14` | تم الارتجاع للراسل |
| `16` | في الطريق للمخزن |
| `17` | استبدال أو استلام طرد |
| `18` | تسليم جزئي |
| `19` | شحنة ملغاة |
| `21` | مرتجع جزئي |
| `22` | مرتجع استبدال |
| `24` | طرد مرتجع |
| `25` | رفض الاستلام ورفض الدفع |
| `26` | في الطريق إلى الفرع |
| `27` | في الطريق للراسل |
| `41` | تحديث شحنات بالفرع |
| `43` | محاولة ثانية |
| `45` | محاولة ثالثة |
| `100` | تعذر تسليم |
| `456` | شحنة مؤجلة |

### 5.9 ملاحظات أمان وربط

- كل طلبات Postex الأصلية تكون `HTTPS`.
- ملف العميل يذكر rate limit: `50` طلب في الدقيقة.
- عند إضافة الشحنات، استخدم bulk بدل طلب لكل شحنة لتقليل الضغط.
- لا ترسل بيانات Postex السرية من المتصفح أو من MEGA؛ خزنها على السيرفر فقط.
- هذا الربط لا يرسل رسائل واتساب، وبالتالي لا يزيد خطر الحظر.

## 6. WhatsApp Bridge API عبر wa-proxy

كل endpoints التالية تستدعى من داخل CRM بهذا الشكل:

```text
/api/wa-proxy.php/api/<endpoint>
```

مثال:

```http
GET /api/wa-proxy.php/api/complaints?status=all&limit=50
```

الـ proxy يضيف تلقائيا:

- `user_id`
- `role`
- `X-Internal-Key`

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

## 7. WhatsApp Sessions

### قائمة الأجهزة/الجلسات

```http
GET /api/wa-proxy.php/api/sessions
```

Query params:

| الاسم | الوصف |
|---|---|
| `all=1` | عرض كل الجلسات للأدمن |

### ربط جلسة جديدة

```http
POST /api/wa-proxy.php/api/sessions/connect
Content-Type: application/json

{
  "id": "wa_user_21",
  "user_id": 21,
  "user_name": "مريم جمال",
  "department": "خدمة العملاء"
}
```

### تعديل بيانات جلسة

```http
PUT /api/wa-proxy.php/api/sessions/{id}
```

أو على Hostinger:

```http
POST /api/wa-proxy.php/api/sessions/{id}/update
```

### QR للجلسة

```http
GET /api/wa-proxy.php/api/sessions/{id}/qr
```

### إيقاف/فصل/حذف

```http
POST /api/wa-proxy.php/api/sessions/{id}/stop
POST /api/wa-proxy.php/api/sessions/{id}/disconnect
DELETE /api/wa-proxy.php/api/sessions/{id}
POST /api/wa-proxy.php/api/sessions/{id}/delete
```

### جروبات جلسة

```http
GET /api/wa-proxy.php/api/sessions/{id}/groups
GET /api/wa-proxy.php/api/sessions/{id}/group-participants
```

## 8. WhatsApp Chats

### قائمة المحادثات

```http
GET /api/wa-proxy.php/api/chats
```

Query params شائعة:

| الاسم | الوصف |
|---|---|
| `session` أو `session_id` | فلترة بجلسة |
| `employee` | فلترة بموظف |
| `q` | بحث |
| `limit` | عدد النتائج |

### رسائل محادثة

```http
GET /api/wa-proxy.php/api/chats/{phoneOrJid}
```

### تعليم قراءة

```http
POST /api/wa-proxy.php/api/chats/{phoneOrJid}/read
```

### إرسال رسالة

```http
POST /api/wa-proxy.php/api/chats/send
Content-Type: application/json

{
  "session_id": "wa_user_21",
  "phone": "201001234567",
  "message": "نص الرسالة",
  "quoted_msg_id": "optional-whatsapp-message-id",
  "mentions": ["201001234567@s.whatsapp.net"]
}
```

### إرسال ميديا

```http
POST /api/wa-proxy.php/api/chats/send-media
```

### React على رسالة

```http
POST /api/wa-proxy.php/api/chats/react
Content-Type: application/json

{
  "session_id": "wa_user_21",
  "phone": "201001234567",
  "message_id": "wa-message-id",
  "emoji": "✅"
}
```

### إجراءات محادثة

```http
POST /api/wa-proxy.php/api/chats/archive
POST /api/wa-proxy.php/api/chats/clear
POST /api/wa-proxy.php/api/chats/delete
POST /api/wa-proxy.php/api/contacts/block
POST /api/wa-proxy.php/api/contacts/rename
GET  /api/wa-proxy.php/api/profile-pic
```

## 9. WhatsApp Complaints / Tickets

هذه endpoints مسؤولة عن الشكاوى، البيكب، التصعيد، حالات الحل، وتقارير الموظفين.

### قائمة الشكاوى

```http
GET /api/wa-proxy.php/api/complaints
```

Query params:

| الاسم | مثال | الوصف |
|---|---|---|
| `status` | `all`, `new`, `reviewing`, `in_progress`, `waiting_agent`, `waiting_customer`, `escalated`, `resolved`, `closed` | فلترة الحالة |
| `case_type` | `service_complaint`, `pickup_request`, `collection` | نوع الشكوى |
| `exclude_case_type` | `pickup_request` | استبعاد نوع |
| `assigned` | `all`, `me`, `unassigned`, `21` | فلترة المسؤول |
| `group_jid` | `120...@g.us` | فلترة جروب |
| `limit` | `50` | حد أقصى 200 |
| `period_hours` | `8` | آخر عدد ساعات |
| `date_from` | `2026-06-01` | من تاريخ |
| `date_to` | `2026-06-08` | إلى تاريخ |
| `year` | `2026` | فلترة سنة |
| `month` | `6` | فلترة شهر |
| `day` | `8` | فلترة يوم |

أمثلة:

```http
GET /api/wa-proxy.php/api/complaints?status=all&exclude_case_type=pickup_request&limit=50
GET /api/wa-proxy.php/api/complaints?case_type=pickup_request&group_jid=120363409126435302@g.us
```

### جروبات الشكاوى

```http
GET /api/wa-proxy.php/api/complaints/groups
```

Query params:

| الاسم | الوصف |
|---|---|
| `case_type=pickup_request` | جروبات البيكب فقط |
| `exclude_case_type=pickup_request` | شكاوى عادية بدون بيكب |

### ملخص الشكاوى

```http
GET /api/wa-proxy.php/api/complaints/summary
```

يرجع:

- الإجمالي
- جديد
- قيد العمل
- تصعيد
- تم الحل
- متأخر
- أداء الموظفين حسب الفترة

### أداء الشكاوى للموظفين

```http
GET /api/wa-proxy.php/api/complaints/performance
```

### شكوى مرتبطة بمحادثة

```http
GET /api/wa-proxy.php/api/complaints/for-chat?phone=201001234567
GET /api/wa-proxy.php/api/complaints/for-chat?group_jid=120...@g.us
```

### تفاصيل شكوى

```http
GET /api/wa-proxy.php/api/complaints/{id}
GET /api/wa-proxy.php/api/complaints/{id}/events
```

### تحديث حالة شكوى

```http
POST /api/wa-proxy.php/api/complaints/{id}/status
Content-Type: application/json

{
  "status": "in_progress",
  "note": "تم استلام المشكلة وجاري المتابعة",
  "assigned_user_id": 21,
  "case_type": "service_complaint",
  "priority": "urgent",
  "resolution_note": ""
}
```

الحالات المدعومة:

```text
new, reviewing, in_progress, waiting_agent, waiting_customer, escalated, resolved, closed
```

الأولويات:

```text
normal, high, urgent
```

### إنشاء شكوى تجريبية

```http
POST /api/wa-proxy.php/api/complaints/simulate
```

أو من PHP:

```http
POST /api/wa-simulate-complaint.php
```

## 10. Pickup

البيكب مبني على نفس نظام الشكاوى لكن `case_type=pickup_request`.

### قائمة طلبات البيكب

```http
GET /api/wa-proxy.php/api/complaints?case_type=pickup_request
```

### جروبات البيكب

```http
GET /api/wa-proxy.php/api/complaints/groups?case_type=pickup_request
```

### تحديث طلب بيكب

```http
POST /api/wa-proxy.php/api/complaints/{id}/status
Content-Type: application/json

{
  "status": "reviewing",
  "note": "تم تأكيد طلب البيكب",
  "case_type": "pickup_request",
  "priority": "high"
}
```

## 11. Cancelled Orders

### قائمة الأوردرات الملغية

```http
GET /api/wa-proxy.php/api/cancelled-orders
```

Query params شائعة:

| الاسم | الوصف |
|---|---|
| `status` | الحالة |
| `q` أو `search` | بحث بكود/رقم/اسم |
| `limit` | عدد النتائج |

### تاريخ أوردر ملغي

```http
GET /api/wa-proxy.php/api/cancelled-orders/{id}/history
```

### تحديث حالة أوردر ملغي

```http
POST /api/wa-proxy.php/api/cancelled-orders/{id}/status
Content-Type: application/json

{
  "status": "confirmed",
  "note": "تم تأكيد البلاغ"
}
```

### إنشاء أوردر ملغي تجريبي

```http
POST /api/wa-proxy.php/api/cancelled-orders/simulate
```

## 12. Successful Orders

### قائمة الأوردرات الناجحة

```http
GET /api/wa-proxy.php/api/successful-orders
```

### تحديث حالة أوردر ناجح

```http
POST /api/wa-proxy.php/api/successful-orders/{id}/status
```

### إنشاء تجريبي

```http
POST /api/wa-proxy.php/api/successful-orders/simulate
```

## 13. WhatsApp Group Customers CRM

### مزامنة أعضاء الجروبات كعملاء

```http
POST /api/wa-proxy.php/api/wa-group-customers/sync
```

### قائمة عملاء جروبات الواتساب

```http
GET /api/wa-proxy.php/api/wa-group-customers
```

Query params:

| الاسم | الوصف |
|---|---|
| `q` | بحث بالاسم/الرقم/الجروب |
| `group_jid` | فلترة جروب |
| `employee_id` | فلترة موظف |
| `status` | فلترة حالة |

### تفاصيل عميل جروب

```http
GET /api/wa-proxy.php/api/wa-group-customers/detail?id=123
```

## 14. WhatsApp Settings & Bot Rules

### إعدادات الواتساب والبوت

```http
GET  /api/wa-proxy.php/api/wa-settings
POST /api/wa-proxy.php/api/wa-settings
```

### قواعد/مسارات البوت

```http
GET    /api/wa-proxy.php/api/bot-rules
POST   /api/wa-proxy.php/api/bot-rules
PUT    /api/wa-proxy.php/api/bot-rules/{id}
POST   /api/wa-proxy.php/api/bot-rules/{id}/update
DELETE /api/wa-proxy.php/api/bot-rules/{id}
POST   /api/wa-proxy.php/api/bot-rules/{id}/delete
```

## 15. WhatsApp Reports

### تقرير أداء الواتساب

```http
GET /api/wa-proxy.php/api/whatsapp/performance-report
```

Query params:

| الاسم | الوصف |
|---|---|
| `employee_id` | موظف محدد |
| `employee_a`, `employee_b` | مقارنة موظف مع موظف |
| `manager_id` | موظفين تحت مدير |
| `period_hours` | آخر عدد ساعات |
| `year`, `month`, `day`, `hour` | فلاتر زمنية |
| `date_from`, `date_to` | نطاق تاريخ |

### تفاصيل نشاط موظف

```http
GET /api/wa-proxy.php/api/whatsapp/employee-activity?employee_id=21
```

Query params:

| الاسم | الوصف |
|---|---|
| `employee_id` | مطلوب |
| `focus` | `all`, `incoming_messages`, `outgoing_messages`, `group_chats` |
| `limit` | عدد الرسائل |
| `period_hours` أو `date_from/date_to` | الفترة |

## 16. CRM Auth

### Login

```http
POST /api/auth.php
Content-Type: application/json

{
  "action": "login",
  "username": "admin",
  "password": "password"
}
```

### Check Session

```http
POST /api/auth.php
Content-Type: application/json

{
  "action": "check"
}
```

### Logout

```http
POST /api/auth.php
Content-Type: application/json

{
  "action": "logout"
}
```

## 17. CRM Users

### قائمة المستخدمين

```http
GET /api/users.php
```

### إضافة مستخدم

```http
POST /api/users.php
Content-Type: application/json

{
  "username": "employee1",
  "password": "strong-password",
  "name": "Employee Name",
  "role": "employee",
  "team": "خدمة العملاء",
  "email": "",
  "phone": "",
  "permissions": "{}",
  "wa_allowed_groups_json": "[]",
  "team_manager_id": 1
}
```

### تعديل مستخدم

```http
POST /api/users.php?_method=PUT
Content-Type: application/json

{
  "id": 21,
  "name": "Employee Name",
  "team": "خدمة العملاء",
  "wa_allowed_groups_json": "[\"120...@g.us\"]"
}
```

### حذف مستخدم

```http
POST /api/users.php?_method=DELETE
Content-Type: application/json

{
  "id": 21
}
```

## 18. Teams

### قائمة الفرق

```http
GET /api/teams.php
```

### إضافة فريق

```http
POST /api/teams.php
Content-Type: application/json

{
  "name": "الشكاوى والاقتراحات",
  "description": "الشكاوى والتأخير",
  "manager_user_id": 1,
  "default_priority": "high",
  "sla_hours": 4,
  "active": 1
}
```

### تعديل فريق

```http
POST /api/teams.php?_method=PUT
Content-Type: application/json

{
  "id": 3,
  "name": "الشكاوى والاقتراحات",
  "manager_user_id": 1,
  "default_priority": "urgent",
  "sla_hours": 2
}
```

### إخفاء فريق

```http
POST /api/teams.php?_method=DELETE
Content-Type: application/json

{
  "id": 3
}
```

## 19. Leads / Customers CRM

### قائمة العملاء

```http
GET /api/leads.php
```

Query params:

| الاسم | الوصف |
|---|---|
| `limit` | عدد النتائج |
| `offset` | بداية النتائج |
| `user_id`, `role`, `team` | صلاحيات/فلترة |

### استيراد عملاء جماعي

```http
POST /api/leads.php
Content-Type: application/json

{
  "action": "bulk_import",
  "leads": [
    {
      "name": "Customer",
      "phone": "201001234567",
      "email": "",
      "country": "مصر",
      "source": "whatsapp"
    }
  ]
}
```

### توزيع عملاء جماعي

```http
POST /api/leads.php
Content-Type: application/json

{
  "action": "bulk_assign",
  "assignments": [
    { "lead_id": 1, "assigned_to": 21 }
  ]
}
```

### إضافة/تعديل/حذف عميل

```http
POST /api/leads.php
POST /api/leads.php?_method=PUT
POST /api/leads.php?_method=DELETE
```

## 20. Calls

### قائمة المكالمات

```http
GET /api/calls.php
```

Query params:

| الاسم | الوصف |
|---|---|
| `lead_id` | عميل |
| `status` | answered/no_answer/busy/failed/completed |
| `date_from`, `date_to` | تاريخ |
| `user_id`, `role`, `team` | صلاحيات |

### حفظ مكالمة

```http
POST /api/calls.php
Content-Type: application/json

{
  "lead_id": 1,
  "lead_name": "Customer",
  "lead_phone": "201001234567",
  "employee_id": 21,
  "employee_name": "Employee",
  "call_sid": "CA...",
  "status": "completed",
  "result": "answered",
  "duration": 120,
  "ring_duration": 10,
  "direction": "outbound",
  "notes": "Call notes"
}
```

## 21. Tasks

### قائمة المهام

```http
GET /api/tasks.php?action=list
```

### تفاصيل مهمة

```http
GET /api/tasks.php?action=get&id=1
```

### إنشاء مهمة

```http
POST /api/tasks.php?action=create
```

### إخفاء إشعار مهمة

```http
POST /api/tasks.php?action=dismiss
```

### تعديل/حذف مهمة

```http
POST /api/tasks.php?_method=PUT
POST /api/tasks.php?_method=DELETE
```

## 22. Invoices

### قائمة الفواتير

```http
GET /api/invoices.php?action=list
```

Query params:

| الاسم | الوصف |
|---|---|
| `status` | draft/sent/paid/cancelled/overdue |
| `search` | بحث |

### تفاصيل فاتورة

```http
GET /api/invoices.php?action=get&id=1
```

### عرض/تحميل مرفق

```http
GET /api/invoices.php?action=view&id=1
GET /api/invoices.php?action=download&id=1
```

### حفظ فاتورة

```http
POST /api/invoices.php
```

يدعم JSON أو form-data مع مرفق.

### تعديل/حذف

```http
POST /api/invoices.php?_method=PUT
POST /api/invoices.php?_method=DELETE
```

## 23. Companies / Twilio

مخصص لحساب المطور/owner فقط.

```http
GET    /api/companies.php
GET    /api/companies.php?id=1
POST   /api/companies.php
POST   /api/companies.php?action=set_default
POST   /api/companies.php?_method=PUT&id=1
POST   /api/companies.php?_method=DELETE&id=1
```

## 24. Twilio / Calls Support APIs

```http
GET  /api/twilio_token.php?identity=USER_ID
POST /api/twilio_voice.php
POST /api/twilio_voice_v2.php
GET  /api/twilio_call_status.php?sid=CALL_SID
GET  /api/twilio_recordings.php?call_sid=CALL_SID
GET  /api/twilio_balance.php
GET  /api/check_balance.php
POST /api/twilio_setup.php
POST /api/mobile_call_sync.php
```

## 25. Reports / Performance

```http
GET /api/reports_stats.php
GET /api/performance.php
GET /api/status_log.php
GET /api/user_activity.php
GET /api/online_status.php
GET /api/notifications.php
```

ملاحظة: بعض هذه endpoints تحتاج Session نشطة، ولذلك لو اتفتحت من curl بدون تسجيل دخول سترجع `Unauthorized`.

## 26. Health Checks

### WhatsApp bridge health من داخل الموقع

```http
GET /api/wa-health.php
```

### WhatsApp bridge health مباشر من الباك إند

```http
GET /api/wa-proxy.php/api/health
```

## 27. أفضل سيناريو لربط MEGA

### المطلوب من MEGA داخل صفحة الشحنة

عند فتح شحنة كودها `PTX12345678`:

1. MEGA يستدعي:

```http
GET https://postex-egypt.tech/api/mega-shipping.php?action=mentions&waybill=PTX12345678&include_groups=1
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
```

2. يعرض داخل الشحنة:

- آخر رسالة تخص الشحنة.
- كل الرسائل المرتبطة بالكود.
- رقم العميل/المرسل.
- اسم الجروب لو الرسالة من جروب.
- الموظف/الجلسة التي استقبلت الرسالة إن وجدت.

### لو MEGA عايز يسجل حركة خارجية

```http
POST https://postex-egypt.tech/api/mega-shipping.php?action=ingest
Authorization: Bearer <MEGA_SHIPPING_API_KEY>
Content-Type: application/json

{
  "waybill": "PTX12345678",
  "message": "تم تحديث حالة الشحنة من MEGA",
  "phone": "201001234567",
  "contact_name": "Customer",
  "direction": "out",
  "session_id": "mega"
}
```

## 28. قواعد مهمة حتى لا يتعطل الربط

- لا تربط ميجا مباشرة على `http://72.62.233.7:3003` إلا لو هذا مقصود داخليا.
- استخدم `api/mega-shipping.php` للربط الخارجي لأنه ثابت وآمن.
- لا ترسل مفاتيح API في query string؛ استخدم Header.
- لا تعتمد على أسماء أعمدة داخل قاعدة البيانات من خارج النظام؛ اعتمد على JSON response فقط.
- عند إضافة endpoint جديد، أضفه هنا بنفس اليوم.
- أي إرسال واتساب آلي لازم يمر على قواعد الحماية من الحظر: لا إرسال جماعي، لا تكرار سريع، ولا رد تلقائي إذا الإعداد مقفول.

## 29. ملفات التنفيذ المهمة

```text
api/config.php               إعدادات قاعدة البيانات والـ bridge والمفاتيح
api/wa-proxy.php             بروكسي الواتساب الداخلي من CRM إلى VPS
api/mega-shipping.php        بوابة الربط الخارجي مع MEGA
api/mega-postex.php          بوابة ربط Postex/Mega لإضافة الشحنات وجلب الحالات والتكاليف
api/auth.php                 تسجيل الدخول والجلسة
api/users.php                المستخدمين والصلاحيات وجروبات الواتساب
api/teams.php                الفرق والمدير والأولوية و SLA
api/leads.php                العملاء الأفراد
api/calls.php                المكالمات
api/notifications.php        الإشعارات
api/online_status.php        حالة الموظفين
/root/follow_wa/index.js     باك إند الواتساب على VPS
```