---
name: n8n Workflow Automation
priority: 3
keywords: n8n, workflow, أتمتة, اوتوميشن, automation, webhook, ويبهوك, زابير, zapier, make, integromat, تدفق عمل, ربط تطبيقات, node, عقدة, trigger, مشغل, $fromAI, ai agent node
---

# n8n Workflow Automation — بناء وتشغيل أتمتة الأعمال

## متى تستخدم
عندما العميل يطلب **أتمتة** مهمة متكررة، ربط تطبيقات ببعض (واتساب ↔ Google Sheets ↔ CRM ↔ بريد)، استقبال leads تلقائياً، أو بناء "تدفق عمل" (workflow). n8n هو محرك الأتمتة (بديل Zapier/Make، لكن self-hosted ومجاني وأقوى).

## الإعداد عندنا (TaseesAI)
- **Instance:** `https://taseesai.app.n8n.cloud`
- الوصول عبر **n8n REST API** (مفتاح API محفوظ في إعدادات الـ gateway). لو ناقص، اطلب من المالك مفتاح API من n8n → Settings → API.
- لكل workflow: نبنيه عبر API (`POST /api/v1/workflows`) أو يدوياً في الواجهة، ثم نفعّله (`activate`).

## مفاهيم n8n الأساسية (لازم تفهمها قبل البناء)
1. **Workflow** = سلسلة **nodes (عُقد)** متصلة. كل node يستقبل بيانات، يعالجها، يمررها للي بعده.
2. **Trigger node (المشغّل)** = أول node، يبدأ التدفق:
   - **Webhook** — يستقبل HTTP POST من أي نظام (الأشهر للـ leads). يعطيك URL.
   - **Schedule/Cron** — يشتغل بوقت محدد.
   - **App triggers** — Gmail جديد، صف جديد في Sheet، رسالة تيليجرام… إلخ.
3. **Regular nodes** = HTTP Request, Set, IF, Switch, Merge, Code, وعقد التطبيقات (Google Sheets, Slack, Supabase…).
4. **Connections** = توصيل مخرج node بمدخل اللي بعده (هي اللي تحدد المسار).

## القاعدة الذهبية لعقدة Code (مهم — 39% من الأخطاء سببها هنا)
- الوضع الافتراضي **Run Once for All Items**: تشتغل مرة وحدة لكل البيانات.
  ```javascript
  const items = $input.all();
  // عالج items هنا
  return [{ json: { result: '...' } }];   // لازم ترجع مصفوفة من {json:...}
  ```
- **دايماً ارجع `return [{json: {...}}]`** — نسيان الـ return أو إرجاع قيمة فارغة = فشل الـ node.
- للبيانات عنصر-عنصر استخدم وضع **Run Once for Each Item** و `$input.item.json`.
- وصول لبيانات node سابق: `$('Node Name').item.json.field` أو `$json.field` للحالي.

## نمط AI Agent Tool (الطريقة الصحيحة — لا تستخدم غيرها)
لما تربط n8n مع وكيل AI ليستدعي أدوات:
- استخدم **`httpRequestTool` (HTTP Request Tool) v4.2** مع تعبيرات **`$fromAI()`** لتمرير قيم يحددها الوكيل وقت التنفيذ.
- مثال قيمة ديناميكية: `={{ $fromAI('email', 'بريد العميل', 'string') }}`.
- **لا تستخدم** `toolCode` ولا `toolHttpRequest` القديمة — `httpRequestTool` + `$fromAI()` هي المعتمدة.

## وصفة جاهزة: التقاط Leads (الأكثر طلباً)
1. **Webhook node** (trigger) → ياخذ POST بـ JSON فيه بيانات العميل. انسخ الـ Production URL.
2. **Set node** → نظّف/سمِّ الحقول (name, phone, source, message).
3. **Supabase / Google Sheets node** → احفظ الـ lead (insert صف).
4. (اختياري) **HTTP Request / WhatsApp** → أرسل تنبيه للمالك "lead جديد".
5. **فعّل (Activate)** الـ workflow → صار الـ Webhook URL حيّ يستقبل 24/7.
> هذا بالضبط نمط KafaatRE (التقاط leads شغّال عبر n8n + Supabase).

## كيف تبني workflow عبر API (للأتمتة البرمجية)
- `GET /api/v1/workflows` — قائمة الـ workflows.
- `POST /api/v1/workflows` — أنشئ واحد جديد (body = JSON فيه `name`, `nodes[]`, `connections{}`).
- `POST /api/v1/workflows/{id}/activate` — فعّله.
- `GET /api/v1/executions?workflowId={id}` — راقب التنفيذات (للـ debugging).
- كل node له: `name`, `type` (مثل `n8n-nodes-base.webhook`), `parameters{}`, `position[x,y]`, و`typeVersion`.

## أخطاء شائعة تجنّبها
- Webhook ما يشتغل؟ تأكد إنك **فعّلت** الـ workflow + تستخدم **Production URL** (مو Test URL).
- Code node يفشل → نسيت `return [{json:...}]`.
- بيانات ما توصل للـ node اللي بعده → ما ربطت الـ connection، أو اسم الحقل غلط في التعبير.
- استدعاء AI tool ما يمرر قيم → استخدم `$fromAI()` داخل `httpRequestTool` مو نص ثابت.

## مبدأ التنفيذ
لو العميل طلب أتمتة: (1) افهم المصدر والوجهة والمشغّل، (2) صمّم الـ nodes ذهنياً، (3) ابنِ عبر API أو اشرح الخطوات بدقة، (4) فعّل واختبر بتنفيذ حقيقي، (5) سلّم الـ Webhook URL أو رابط الـ workflow كدليل عمل. لا تقول "تم بناء الأتمتة" إلا بعد ما تفعّلها فعلاً.
