البدء

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

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

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

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

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

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

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

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

Code
cd cod-client-astro
npm run seed:admin
npm run dev

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

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

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

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

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

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

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

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

Code
X-API-Key: cod_your_api_key_here

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

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

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

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

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

Code
X-Store-API-Key: your_store_api_key_here

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

إرسال أول طلب

curl http://localhost:8787/api/orders \
  -H "X-API-Key: $COD_API_KEY"

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

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

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

يتضمن مرجع API ساحة تجربة تفاعلية.

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

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

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

اقرأ المصادقة لمعرفة نموذج المصادقة الكامل وقواعد النطاقات.
اقرأ الأخطاء قبل كتابة منطق إعادة المحاولة.
استخدم Webhooks لاستقبال أحداث متجرك على خادمك، واقرأ Webhooks شركات التوصيل لمعرفة كيف تبلّغ شركات التوصيل عن التسليمات.
اربط عميل ذكاء اصطناعي عبر خادم MCP.

مقدمة المصادقة