# البدء

يرشدك هذا الدليل من خادم CodFlow محلي إلى طلب مُصادَق. إذا كانت لديك نسخة منشورة، فتجاوز الإعداد المحلي واستخدم أصل API الخاص بها.

## عناوين URL الأساسية

| البيئة | عنوان URL الأساسي | ملاحظات |
| --- | --- | --- |
| محلي | `http://localhost:8787` | `wrangler dev` داخل `cod-server` |
| الإنتاج | `https://api.codflow.store` | واجهة API العامة لـ CodFlow |

كل نقطة نهاية للتاجر تقع تحت `/api/*`. ونقاط نهاية واجهة المتجر تحت `/store/*`، وعمليات callback الخاصة بشركات التوصيل تحت `/webhooks/*`.

## تشغيل API محليًا

من جذر المستودع:

```bash
npm ci
cd cod-server
npm run db:setup:local
npm run dev
```

يبدأ الخادم على `http://localhost:8787`. في طرفية ثانية، هيّئ مسؤول لوحة التحكم وابدأ لوحة التحكم:

```bash
cd cod-client-astro
npm run seed:admin
npm run dev
```

تعمل لوحة التحكم على `http://localhost:4321`.

:::tip
حالة D1 المحلية مشتركة عبر `.wrangler-shared`. إذا فشل تسجيل الدخول عند أول استنساخ للمستودع، فشغّل `npm run db:setup:local` قبل `npm run seed:admin`.
:::

## الحصول على مفتاح API

يستخدم CodFlow نوعين من المفاتيح، وهما غير قابلين للتبادل.

### مفتاح API للتاجر

استخدم مفتاح تاجر مع `/api/*`. ينتمي إلى مستخدم في لوحة التحكم ويرث دوره ونطاقاته.

1. افتح لوحة التحكم وانتقل إلى **الفريق**.
2. أنشئ مفتاحًا لعضو في الفريق، أو دوّر مفتاحًا موجودًا.
3. انسخ المفتاح عند عرضه. لن يُعرض مرة أخرى.

أرسله في ترويسة `X-API-Key`:

```http
X-API-Key: cod_your_api_key_here
```

يمكن للمسؤول استخدام كل النطاقات. أما مستخدم الطاقم فيمكنه استخدام الأدوات ونقاط النهاية المسموح بها فقط وفق النطاقات المخصصة له.

### مفتاح API لواجهة المتجر

استخدم مفتاح متجر مع `/store/*`. يعرّف المتجر لدى API واجهة المتجر العامة.

1. افتح لوحة التحكم وانتقل إلى **الإعدادات**.
2. افتح **مفتاح API للمتجر** في الشريط الجانبي للإعدادات.
3. اكشف المفتاح وانسخه.

أرسله في ترويسة `X-Store-API-Key`:

```http
X-Store-API-Key: your_store_api_key_here
```

:::warning
يمكن لمفتاح التاجر قراءة بيانات المتجر وتغييرها. احتفظ به على الخادم، في مدير أسرار أو سر Worker. لا تضعه أبدًا في حزمة واجهة متجر أو تطبيق متصفح أو مستودع git.
:::

## إرسال أول طلب

<CodeTabs>

```bash title="Merchant API"
curl http://localhost:8787/api/orders \
  -H "X-API-Key: $COD_API_KEY"
```

```bash title="Storefront API"
curl "http://localhost:8787/store/products?limit=5" \
  -H "X-Store-API-Key: $STORE_API_KEY"
```

</CodeTabs>

تحتوي استجابة القائمة الناجحة على مصفوفة `data` و`count`:

```json
{
  "success": true,
  "data": [],
  "count": 0
}
```

## استخدام ساحة التجربة

يتضمن [مرجع API](/api) ساحة تجربة تفاعلية.

1. اختر **Local development** في محدّد الخادم (أو **Production** لنسخة منشورة).
2. اضغط **Authorize** وألصق المفتاح الخاص بالمخطط الذي تختبره: `X-API-Key` أو `X-Store-API-Key`.
3. افتح عملية، واملأ المعاملات، وأرسل الطلب.

في التطوير المحلي يعيد الخادم أصل الطلب، لذا يمكن لموقع التوثيق هذا على `http://localhost:3000` استدعاؤه مباشرة.

## الخطوات التالية

- اقرأ [المصادقة](/ar/authentication) لمعرفة نموذج المصادقة الكامل وقواعد النطاقات.
- اقرأ [الأخطاء](/ar/errors) قبل كتابة منطق إعادة المحاولة.
- استخدم [Webhooks](/ar/webhooks) لاستقبال أحداث متجرك على خادمك، واقرأ [Webhooks شركات التوصيل](/ar/carrier-webhooks) لمعرفة كيف تبلّغ شركات التوصيل عن التسليمات.
- اربط عميل ذكاء اصطناعي عبر [خادم MCP](/ar/mcp).