---
name: Generic API Integration (the "plug")
priority: 3
keywords: api, rest api, webhook, integration, تكامل, ربط api, ربط نظام, connect, http, curl, oauth, swagger, openapi, postman, integrate
---

# Generic API Integration — The Universal "Plug"

## متى تستخدم
عندما العميل يطلب الربط بنظام/API ما عندنا له skill مخصص له (مثلاً: نظام داخلي، API محلي، أو SaaS غير مذكور). هذي المهارة تعلّم Muassis كيف يدمج أي شيء.

## الإطار الفائز (5 خطوات)

### 1. استكشف
```bash
# اقرأ documentation
exec_command "curl -s 'https://api.example.com/docs/openapi.json' | head -100"

# جرّب endpoint بسيط
exec_command "curl -s -i 'https://api.example.com/v1/health'"
```

### 2. اعرف المصادقة
معظم APIs تستخدم واحدة من هذي:
| النوع | كيف تبعت | أمثلة |
|---|---|---|
| API Key | Header: `X-API-Key: <key>` أو query: `?key=<key>` | Stripe، Twilio |
| Bearer Token | Header: `Authorization: Bearer <token>` | HubSpot، Salesforce |
| Basic Auth | Header: `Authorization: Basic <base64(user:pass)>` | Mailchimp |
| OAuth2 | refresh_token → access_token cycle | Google، Meta |
| HMAC | signature عبر secret + body hash | Shopify webhooks |

اطلب من العميل المفتاح، احفظه في `<dataDir>/.env`:
```bash
exec_command "echo 'EXAMPLE_API_KEY=xxx' >> $HOME/Library/Application\\ Support/Muassis/.env"
```
أو استدعِ `tryQuickConfig` بـ`KEY=VALUE`.

### 3. اختبر CRUD
لكل API: جرّب
- GET (list + by id)
- POST (create)
- PUT/PATCH (update)
- DELETE (احذف بحذر!)

### 4. تعلّم الـrate limits
- اقرأ headers مثل `X-RateLimit-Remaining` بعد كل call.
- لو وصلت للـlimit، انتظر قبل ما تكمل.
- استخدم exponential backoff على 429:
```bash
for i in 1 2 4 8 16; do
  RESP=$(curl -s -w '%{http_code}' "$URL")
  CODE="${RESP: -3}"
  if [ "$CODE" -ne 429 ]; then break; fi
  sleep $i
done
```

### 5. ولّد wrapper script + skill جديد
بعد ما تتأكد API يعمل، احفظ:
```bash
write_file ~/MuassisNotes/api-{service}-cookbook.md:
"# {Service} API Cookbook
## Auth: ...
## Common ops: ...
## Errors I hit: ..."
```
ثم اقترح على المالك إنشاء skill رسمي للنظام لو حيتكرر استخدامه.

## أنماط شائعة لأي API

### Pagination
- **Cursor-based** (الأفضل): `?cursor=<next_cursor>`
- **Page-based**: `?page=2&per_page=50`
- **Offset-based**: `?offset=100&limit=50`
- اقرأ الـheaders/body للـnext URL.

### Filtering
- **Query params**: `?status=active&created_after=2026-05-01`
- **Body filters** (POST search): `{"filterGroups": [...]}`
- **GraphQL**: `{ users(where: {status: {_eq: "active"}}) { id name } }`

### Webhooks (incoming)
عشان تستلم events من نظام خارجي:
1. اعمل endpoint في Muassis (في `src/web-chat/routes.ts` أو راوت مخصص).
2. تحقق من signature (HMAC) لو الـAPI يدعم.
3. استلم → خزّن → احذف من الـqueue.

### Webhook signature verification (Shopify-style HMAC)
```bash
echo -n "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -binary | base64
# قارن مع X-Shopify-Hmac-Sha256 header
```

## إستراتيجية للـSaaS غير المعروف

1. **GitHub search** لكلمة الـSaaS + "openapi.json" أو "swagger.json".
2. **Postman public APIs**: https://www.postman.com/explore (90% من APIs المعروفة موجودة).
3. **اسأل ChatGPT / Claude API** للحصول على cookbook سريع.
4. **اقرأ webhook logs** لو العميل عنده integration سابق — يكشف الـdata shape.

## أمثلة
- "اربط Muassis مع نظام POS عندي على endpoint http://192.168.1.10/api" → curl GET على /api، استكشف، استخرج format.
- "ابعث webhook للنظام الفلاني كل ما تجي طلب جديد" → سجّل URL في `<dataDir>/webhooks.json`، ربطه بـSalla webhook handler.
- "اعمل skill جديد لـStripe" → اقرأ docs، اكتب skill بنفس format، احفظ في `<dataDir>/skills/`.

## القواعد الذهبية
- ❌ **ممنوع** call على production API بدون اختبار في sandbox أولاً.
- ❌ **لا تخزّن secrets في git** أو في dashboard logs — `.env` فقط.
- ✅ **اقرأ الـrate limits** قبل أي batch operation.
- ✅ **سجّل كل call (request + response)** في `~/MuassisNotes/api-debug-{date}.log` للـdebugging.
- ✅ **استخدم idempotency keys** على create operations لمنع التكرار (Stripe بـIdempotency-Key header، أو generate UUID لكل request).
