---
name: ERP / Accounting Integration
priority: 2
keywords: erp, accounting, محاسبة, حسابات, دفتر, دفاتر, ledger, journal, خبرة محاسبية, finance, integration, تكامل, ربط, محاسب, زوهو, kwikbooks, quickbooks, xero, odoo, sage, netsuite, sap, sap b1, dynamics, قيود, ميزانية, balance, p&l, cash flow, expense, نفقات, مصاريف, إيرادات, revenue, receivables, payables, مستحقات
---

# ERP / Accounting Integration — Plug-and-Play

## متى تستخدم / When to use
عندما يطلب العميل ربط/مزامنة/استخراج بيانات من نظام محاسبي أو ERP — Zoho Books، QuickBooks، Xero، Odoo، SAP B1، NetSuite، Microsoft Dynamics 365 Business Central، Sage، Qoyod، Dafater. أو لما يحتاج إنشاء/تحديث/قراءة فاتورة، قيد محاسبي، تقرير مالي، تسوية بنكية، أو حساب من ERP خارجي.

## كيف تنفّذ / Instructions

### الخطوة 0: تحديد ERP والمصادقة
اسأل العميل عن:
1. أي نظام (Zoho Books / QuickBooks / Xero / Odoo / Qoyod / غيره)
2. لو ما يعرف، اقترح فحص `~/.muassis/.env` بـ `read_file` للمفاتيح المسجلة:
   - `ZOHO_BOOKS_TOKEN`, `ZOHO_ORG_ID`
   - `QUICKBOOKS_TOKEN`, `QUICKBOOKS_REALM_ID`
   - `XERO_TOKEN`, `XERO_TENANT_ID`
   - `ODOO_URL`, `ODOO_DB`, `ODOO_API_KEY`
3. لو مفقود، اطلب من العميل لصقه (الـ env loader يخزنه تلقائياً).

### Zoho Books (شائع في MENA)
Auth: OAuth2 token. Base: `https://www.zohoapis.com/books/v3`
```bash
# قائمة الفواتير
exec_command "curl -s -H 'Authorization: Zoho-oauthtoken $ZOHO_BOOKS_TOKEN' 'https://www.zohoapis.com/books/v3/invoices?organization_id=$ZOHO_ORG_ID&per_page=20'"

# إنشاء فاتورة
exec_command "curl -s -X POST -H 'Authorization: Zoho-oauthtoken $ZOHO_BOOKS_TOKEN' -H 'Content-Type: application/json' -d @/tmp/invoice.json 'https://www.zohoapis.com/books/v3/invoices?organization_id=$ZOHO_ORG_ID'"

# قائمة العملاء
exec_command "curl -s -H 'Authorization: Zoho-oauthtoken $ZOHO_BOOKS_TOKEN' 'https://www.zohoapis.com/books/v3/contacts?organization_id=$ZOHO_ORG_ID'"

# تقرير الـP&L
exec_command "curl -s -H 'Authorization: Zoho-oauthtoken $ZOHO_BOOKS_TOKEN' 'https://www.zohoapis.com/books/v3/reports/profitandloss?organization_id=$ZOHO_ORG_ID&from_date=2026-01-01&to_date=2026-12-31'"
```

### QuickBooks Online
Auth: OAuth2. Base: `https://quickbooks.api.intuit.com/v3/company/{realmId}`
```bash
# قائمة الفواتير (SQL-like query)
exec_command "curl -s -H 'Authorization: Bearer $QUICKBOOKS_TOKEN' -H 'Accept: application/json' 'https://quickbooks.api.intuit.com/v3/company/$QUICKBOOKS_REALM_ID/query?query=SELECT * FROM Invoice MAXRESULTS 20'"

# إنشاء فاتورة
exec_command "curl -s -X POST -H 'Authorization: Bearer $QUICKBOOKS_TOKEN' -H 'Content-Type: application/json' -d @/tmp/invoice.json 'https://quickbooks.api.intuit.com/v3/company/$QUICKBOOKS_REALM_ID/invoice'"
```

### Xero
Auth: OAuth2. Base: `https://api.xero.com/api.xro/2.0`
```bash
exec_command "curl -s -H 'Authorization: Bearer $XERO_TOKEN' -H 'Xero-tenant-id: $XERO_TENANT_ID' -H 'Accept: application/json' 'https://api.xero.com/api.xro/2.0/Invoices'"
```

### Odoo (شائع، self-hosted)
Auth: API key أو session. Base: `$ODOO_URL/api/v2`
```bash
# مصادقة + استدعاء RPC
exec_command "curl -s -H 'Content-Type: application/json' -d '{\"jsonrpc\":\"2.0\",\"method\":\"call\",\"params\":{\"service\":\"object\",\"method\":\"execute_kw\",\"args\":[\"$ODOO_DB\",1,\"$ODOO_API_KEY\",\"account.move\",\"search_read\",[[[\"move_type\",\"=\",\"out_invoice\"]]],{\"fields\":[\"name\",\"partner_id\",\"amount_total\",\"state\"],\"limit\":20}]}}' '$ODOO_URL/jsonrpc'"
```

### Qoyod (Saudi-specific)
Auth: API token. Base: `https://www.qoyod.com/api/2.0`
```bash
exec_command "curl -s -H 'API-KEY: $QOYOD_TOKEN' 'https://www.qoyod.com/api/2.0/invoices'"
```

## أنماط عامة (أي ERP)
1. **اقرأ قبل الكتابة** — فبل ما تنشئ فاتورة، اقرأ العميل/المنتج عشان تطلع IDs الصحيحة.
2. **احفظ الـIDs في الذاكرة** — استدعِ `remember` بعد كل قراءة عشان ما ترجع للAPI كل مرة.
3. **بعد الكتابة، أكّد** — اقرأ السجل المنشأ ولاقي رقمه/IDه قبل ما تبلّغ العميل.
4. **معالجة الأخطاء** — معظم الـAPIs ترجع 401 (token expired)، 404 (مش موجود)، 422 (validation). اعرض الرد الفعلي للعميل.

## أمثلة / Examples
- "ابغى فاتورة لأحمد بـ500 ريال في Zoho" → اقرأ contact_id لأحمد، أنشئ فاتورة، أبلّغ بالرقم الفعلي.
- "كم مستحقات هذا الشهر في QuickBooks" → SQL query على Invoice WHERE Balance > 0.
- "زامن المنتجات من Salla إلى Zoho" → loop: read Salla products → upsert Zoho items.
- "تقرير ربح وخسارة آخر 90 يوم" → `reports/profitandloss` مع التواريخ، اعرض الـtotal revenue/expense/net.

## القواعد الذهبية
- ❌ **ممنوع** اختراع invoice IDs أو معرفات حسابية — استخدم الردود الفعلية فقط.
- ❌ **ممنوع** لمس بيانات إنتاجية بدون موافقة صريحة من المالك ("هل تأكدت؟").
- ✅ **سجّل كل تعامل** بـ `remember` عشان تكون عندك ذاكرة عبر المحادثات.
- ✅ **استخدم sandbox/test environment** لو الـERP يدعمه قبل الإنتاج.
