# 📡 API ربط نظام المبيعات بنظام المستودع (Magic Tech)

> هذا الملف موجّه لمبرمج نظام المبيعات. الهدف: عند إصدار/تجهيز فاتورة، يرسل نظام المبيعات الفاتورة تلقائياً لنظام المستودع، فتظهر هناك كـ "طلب وارد" يقبله أمين المستودع ويخصم البضاعة.

---

## 🔗 نقطة الاتصال (Endpoint)

طلب واحد فقط (`POST`) لكل فاتورة:

```
POST  https://csimxfjopsndlmdfouuh.supabase.co/rest/v1/rpc/ingest_sales_order
```

### الترويسات (Headers) — إلزامية

| Header | القيمة |
|---|---|
| `apikey` | `sb_publishable_Q8GTbJauvaBVl6BejBzSoQ_et2D0c1y` |
| `Authorization` | `Bearer sb_publishable_Q8GTbJauvaBVl6BejBzSoQ_et2D0c1y` |
| `Content-Type` | `application/json` |

> هذا المفتاح عام (publishable) — لا خطر منه. الحماية الفعلية عبر **السر** داخل جسم الطلب (`token`).

---

## 📦 جسم الطلب (Body) — JSON

```json
{
  "token": "ضع_هنا_السر",
  "external_id": "INV-2026-000123",
  "invoice_no": "123",
  "invoice_date": "2026-06-10T14:30:00",
  "customer_name": "محمد أحمد",
  "seller_name": "اسم البائع",
  "note": "ملاحظة على الفاتورة (اختياري)",
  "total_amount": 450.000,
  "items": [
    { "model": "DS-2CD1043", "qty": 3, "unit_price": 25.000, "barcode": "6291100012345", "description": "كاميرا 4MP" },
    { "model": "CAT6-305",   "qty": 1, "unit_price": 120.000 }
  ]
}
```

### شرح الحقول

| الحقل | إلزامي؟ | الوصف |
|---|---|---|
| `token` | ✅ | السر المتفق عليه (نفس الموجود في دالة SQL). بدونه يُرفض الطلب. |
| `external_id` | ⭐ مهم | رقم الفاتورة **الفريد** في نظام المبيعات. يمنع تكرار نفس الفاتورة لو انبعتت مرتين. |
| `invoice_no` | اختياري | رقم الفاتورة المعروض للمستخدم. |
| `invoice_date` | اختياري | تاريخ/وقت الفاتورة (ISO 8601). لو فاضي يُستخدم وقت الاستلام. |
| `customer_name` | اختياري | اسم العميل. |
| `seller_name` | اختياري | اسم البائع. |
| `note` | اختياري | ملاحظة. |
| `total_amount` | اختياري | قيمة الفاتورة. |
| `items` | ✅ | مصفوفة البنود. |
| `items[].model` | ✅* | **موديل الصنف** — لازم يطابق الموديل في نظام المستودع تماماً. |
| `items[].barcode` | ⭐ أفضل | الباركود. لو موجود، المطابقة تصير فيه أولاً (أدق من الموديل). |
| `items[].qty` | ✅ | الكمية. |
| `items[].unit_price` | اختياري | سعر الوحدة. |
| `items[].description` | اختياري | وصف يساعد أمين المستودع لو الصنف ما تطابق. |

> **\*** لكل بند لازم يكون فيه `barcode` **أو** `model` على الأقل. الأفضل الاثنين.

### 🔑 قاعدة المطابقة (مهمة)
النظام بيطابق الصنف هيك:
1. لو فيه `barcode` ويتطابق مع باركود صنف عندنا → ربط مباشر ✅
2. وإلا، لو `model` يتطابق (حرفياً، غير حسّاس لحالة الأحرف) مع موديل صنف عندنا → ربط ✅
3. لو ما تطابق → البند بيوصل بحالة `unmatched`، وأمين المستودع بيربطه يدوياً من الصفحة.

➡️ **عشان الربط يصير 100% تلقائي: خلّي الموديلات (أو الباركود) في نظام المبيعات نفسها الموجودة عندنا.**

---

## ✅ الرد (Response)

نجاح:
```json
{ "ok": true, "order_id": 45, "lines": 2 }
```

فاتورة مكررة (انبعتت قبل — تجاهلها):
```json
{ "ok": true, "duplicate": true, "order_id": 45 }
```

سر خاطئ:
```json
{ "code": "P0001", "message": "unauthorized: invalid token" }
```

---

## 🧪 مثال جاهز (cURL)

```bash
curl -X POST "https://csimxfjopsndlmdfouuh.supabase.co/rest/v1/rpc/ingest_sales_order" \
  -H "apikey: sb_publishable_Q8GTbJauvaBVl6BejBzSoQ_et2D0c1y" \
  -H "Authorization: Bearer sb_publishable_Q8GTbJauvaBVl6BejBzSoQ_et2D0c1y" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "ضع_هنا_السر",
    "external_id": "INV-2026-000123",
    "invoice_no": "123",
    "customer_name": "محمد أحمد",
    "items": [ { "model": "DS-2CD1043", "qty": 3 } ]
  }'
```

### مثال C# (HttpClient)
```csharp
var payload = new {
    token = "ضع_هنا_السر",
    external_id = invoiceNo,
    invoice_no = invoiceNo,
    customer_name = customer,
    items = lines.Select(l => new { model = l.Model, qty = l.Qty, barcode = l.Barcode })
};
var json = System.Text.Json.JsonSerializer.Serialize(payload);
var req = new HttpRequestMessage(HttpMethod.Post,
    "https://csimxfjopsndlmdfouuh.supabase.co/rest/v1/rpc/ingest_sales_order");
req.Headers.Add("apikey", "sb_publishable_Q8GTbJauvaBVl6BejBzSoQ_et2D0c1y");
req.Headers.Add("Authorization", "Bearer sb_publishable_Q8GTbJauvaBVl6BejBzSoQ_et2D0c1y");
req.Content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");
var res = await httpClient.SendAsync(req);
```

---

## 🕒 متى تُرسل الفاتورة؟
الأفضل: عند **اعتماد/إصدار** الفاتورة في نظام المبيعات (مش وهي مسوّدة). كل فاتورة تُرسل مرة واحدة. لو انبعتت مرتين بنفس `external_id` ما بتتكرر (آمن).

---

## ⚠️ ملاحظات
- لا تُرسل أسعار سالبة أو كميات صفر.
- التاريخ بصيغة ISO: `2026-06-10T14:30:00`.
- لو بدك تختبر: ابعت فاتورة تجريبية وراقبها بصفحة "طلبات واردة" في نظام المستودع.
- السر (`token`) لازم يكون نفسه المكتوب داخل دالة `ingest_sales_order` في قاعدة البيانات.