الرئيسية / API

API

اربط تقدّم مشاريع المتاجر بنظامك الخاص: في أي خطوة وصل المشروع، وإلى أين وصلت البضاعة، وهل التدريب على المسار الصحيح. جميع الواجهات للقراءة فقط، دون تسجيل ودون API Key .

الاصطلاحات الأساسية

Base URL: https://www.icook.cloud
المصادقة: الواجهات المدرجة في هذه الصفحة لا تتطلب أي بيانات اعتماد؛ أما الواجهات المتاحة بالرمز فبيانات الاعتماد فيها هي token الموجود في الرابط نفسه
الصيغة: JSON (application/json; charset=utf-8)، وجميع الأوقات بتوقيت UTC
الأخطاء: 400 معامل غير صالح · 401 رمز الدخول مفقود · 404 غير موجود، ومتن الاستجابة يأتي بالصيغة {"error":"…"}
طلبات عبر المصادر: لا تُعاد ترويسات CORS — تُحجَب الاستدعاءات عبر المصادر الصادرة من المتصفح، ويُرجى الاستدعاء من الخادم لديك. وإذا احتجت فعلًا إلى اتصال مباشر من المتصفح فراسلنا موضحًا نطاق المصدر.
معدل الطلبات: لا توجد حصة صارمة. يُرجى الاعتماد على التخزين المؤقت لديك؛ استقصاء تقدّم المشاريع مرة كل دقيقة كافٍ، فلا تستقصِ كل ثانية.
الإصدار: لا يوجد رقم إصدار. الحقول تُضاف ولا تُحذف؛ وإذا استلزم الأمر تعديلًا غير متوافق، فسيتم إخطار المستخدمين المعروفين للواجهة مسبقًا عبر البريد الإلكتروني.

هذه الواجهات هي التي تشغّل صفحات الموقع العامة نفسها — ما تراه معروضًا في صفحة المشروع هو ما تعيده الواجهة، لا أكثر ولا أقل.

البيانات المفتوحة

لا حاجة إلى أي بيانات اعتماد. مناسبة لربط تقدّم المشاريع بلوحة المعلومات الخاصة بك.

GET/api/projects

قائمة مشاريع المتاجر قيد التنفيذ. المشاريع ذات الحالة «قيد التنفيذ».

الحقل	الوصف
`id`	رقم المشروع؛ معامل المسار لبقية الواجهات
`name / biz_type / city`	اسم المشروع · نوع النشاط · المدينة
`status`	active (قيد التنفيذ) · بقية القيم حالات مؤرشفة
`current_stage`	الخطوة الحالية ضمن الخطوات التسع، 1–9
`note`	ملاحظة خلفية عامة في جملة واحدة (حقل عام)
`track / cuisine`	مسار اختيار الموقع / فئة القائمة؛ القيم مشتركة مع المكتبات
`submission_count`	عدد المقترحات المستلمة (العدد فقط، دون المحتوى)
`stage_counts`	عدد المقترحات لكل مرحلة، بالصيغة { "5": 12 }
`created_at`	وقت إنشاء المشروع، UTC

GET/api/projects/:id

تفاصيل مشروع واحد. تتضمن ثلاثة حقول حالة إضافية عابرة للمراحل مقارنة باستجابة القائمة.

الحقل	الوصف
`…`	يتضمن جميع حقول استجابة القائمة
`opening_status`	⑨ مصطلح حالة دورة الافتتاح (الحالة فقط، دون بيانات التشغيل)
`training_status`	⑧ مصطلح حالة دورة التدريب
`accepted_count`	عدد المقترحات المعتمدة

الإيرادات والتكاليف والمشكلات والمسؤول وتاريخ الافتتاح لا تُعاد كحقول أصلًا — هذا خط أحمر في التصميم، وليس سهوًا.

GET/api/projects/:id/sites

القائمة المختصرة بالمحلات التجارية المرشحة للمشروع (مخرَج مرحلة ② اختيار الموقع).

الحقل	الوصف
`site_id`	معرّف المحل التجاري في مكتبة المواقع؛ تفاصيل المحل التجاري في مكتبة المواقع، ويُخزَّن هنا المرجع فقط
`external_title / external_url`	عنوان ورابط لمحل تجاري خارج المكتبة
`status`	pending بانتظار الزيارة الميدانية · visited تمت الزيارة الميدانية · chosen تمّ اختياره · rejected تمّ رفضه
`note`	ملاحظة على المرشَّح

تنبيه: الحقل `note` حقل عام يُعرض علنًا مع صفحة المشروع. عند كتابة الملاحظات تعامل معها على أنها علنية — لا تكتب الحد الأدنى للسعر، ولا أسماء المنافسين، ولا أي تقدير لا ينبغي أن يُرى.

GET/api/projects/:id/menus

القائمة المختصرة بالقوائم المرشحة للمشروع (مخرَج مرحلة ① التشخيص). بنيتها مطابقة لبنية المحلات التجارية المرشحة، وتُخزَّن مراجع menu_id فقط.

الحقل	الوصف
`menu_id`	معرّف القائمة في مكتبة القوائم
`status / note`	كما في المحلات التجارية المرشحة

GET/api/projects/:id/shipments

تقدّم الشحن الخاص بالمشروع. مع إخفاء البيانات: لا يُعاد سوى عدد الإرساليات، ومرحلتها الحالية، وتاريخ الوصول، وعدد الصناديق.

الحقل	الوصف
`id`	رقم الإرسالية
`cargo_class`	food أغذية · general غير أغذية
`transport_mode`	sea_fcl حاوية كاملة · sea_lcl حمولة مجمّعة · air شحن جوي · ground نقل بري داخل الولايات المتحدة
`cold_chain`	هل تُستخدم سلسلة التبريد، 0 / 1
`status`	حالة قائمة التعبئة
`node`	depart غادرت · transit قيد النقل · arrived وصلت إلى الميناء · customs التخليص الجمركي · final_mile المرحلة الأخيرة · delivered سُلّمت
`eta`	تاريخ الوصول المتوقع إلى الميناء
`item_count / carton_total`	عدد صفوف البضائع / إجمالي عدد الصناديق

لا تُعاد سوى الإرساليات النهائية وما بعدها. ولا تُعاد قيمة البضاعة أو HS CODE أو عنوان الاستلام أو الناقل أو رقم بوليصة الشحن إطلاقًا.

GET/api/projects/:id/training-readiness

جاهزية المشروع لمرحلة ⑧ التدريب. أعداد مجمّعة فقط؛ لا قوائم أسماء ولا معلومات شخصية.

الحقل	الوصف
`started / status`	هل بدأت · مصطلح حالة الدورة
`staffed / plan_total`	عدد الموظفين الفعلي / عدد الموظفين المخطط له
`cert_passed / cert_required`	بنود الاعتماد المجتازة / بنود الاعتماد المطلوبة
`critical_passed / critical_required / critical_pending`	البنود الحرجة المجتازة / المطلوبة / غير المجتازة
`hollow`	هل هي في الحالة الفارغة التي تُعرض فيها الدرجة الكاملة بمجرد إدخال بند واحد
`ready`	هل استُوفت شروط التدريب اللازمة للافتتاح

تُحسب نسبة الإنجاز على أساس البنود المطلوبة، لا على أساس الصفوف المنشأة — ولذلك يكون `cert_required` عادةً أكبر بكثير من عدد الصفوف المُدخلة.

الواجهات المتاحة بالرمز

الرابط هو بيانات الاعتماد. نُصدر token مرفقًا برابط العمل المعني، ولا يمكن طلبه عبر قنوات عامة — كل رابط تستلمه يفتح المستند المرتبط به وحده.

GET/api/ticket/:code

حالة تقييم المقترح. الرمز code هو رمز الاستعلام المكوّن من 8 خانات الذي تمنحه صفحة نجاح الإرسال.

الحقل	الوصف
`title / supplier`	عنوان المقترح / اسم الشركة المُقدِّمة
`stage`	المرحلة المرتبطة، 1–9
`status`	new (تقديم جديد) · reviewing (قيد التقييم) · accepted (مقبول) · rejected (غير مقبول)
`created_at`	وقت التقديم، UTC

لا يُعاد إرسال نص المقترح ولا عرض السعر ولا المرفقات.

GET/api/quote/:token

عرض سعر للعميل. يأتي token من رابط /q/ أصدرناه نحن.

الحقل	الوصف
`title / category / stage`	عنوان عرض السعر · الفئة · المرحلة
`quote_amount / quote_currency`	مبلغ عرض السعر الموجّه للعميل والعملة
`member_discount`	نسبة خصم الأعضاء؛ 0 يعني عدم تحديد شريحة سعر للأعضاء
`items[]`	أسطر البنود: name · spec · unit · qty · sale_price · category · img_url
`shipments[]`	تقدّم الشحن المرتبط (كما في الأعلى، مع إخفاء البيانات)

عروض الأسعار ذات رمز الدخول تتطلب `?pass=<رمز-الدخول>`؛ وإلا كانت الاستجابة 401. سعر التكلفة ونسبة الترميز والهامش الإجمالي لا تُعاد أبدًا.

GET/api/booking/:token

وجهة رابط العميل لقائمة التعبئة اللوجستية. يأتي token من رابط /logistics/f/ أصدرناه نحن؛ تُعبّأ قوائم التعبئة على freight.icook.cloud، ولا تُعيد نقطة النهاية هذه إلا رابط العميل المقابل.

الحقل	الوصف
`redirect`	رابط العميل في freight، ويتضمن ?pass= عند تقديم رمز الدخول الصحيح؛ null عند عدم وجود قائمة تعبئة مقابلة
`note`	توضيح عند عدم وجود قائمة تعبئة مقابلة

يدعم أيضًا `?pass=`. لا يُعاد محتوى قائمة التعبئة.

GET/api/booking-share/:token

وجهة رابط الناقل لقائمة التعبئة اللوجستية. يأتي token من رابط /logistics/s/ أصدرناه نحن؛ ولا تُعيد نقطة النهاية هذه إلا رابط الناقل المقابل في freight.

الحقل	الوصف
`redirect`	رابط الناقل في freight؛ null عند عدم وجود قائمة تعبئة مقابلة
`note`	توضيح عند عدم وجود قائمة تعبئة مقابلة؛ فارغ عند وجود وجهة

لا يُعاد محتوى قائمة التعبئة.

جرّبها

curl https://www.icook.cloud/api/projects

# مشروع واحد
curl https://www.icook.cloud/api/projects/1

# تقدّم الشحن (مع إخفاء البيانات)
curl https://www.icook.cloud/api/projects/1/shipments

# رمز متابعة تجريبي / عرض سعر تجريبي (المستخدمان في الدليل)
curl https://www.icook.cloud/api/ticket/GUIDE2026
curl https://www.icook.cloud/api/quote/GUIDEQUOTE26

ما لا نوفّره

لا توجد واجهات كتابة عامة. لإرسال مقترح أو طلب العضوية أو ملء قائمة التعبئة أو تعديل كميات عرض السعر، استخدم نماذج الويب — فهي تتضمن التدابير اللازمة ضد إساءة الاستخدام، وتُرفض الطلبات التي تتجاوز النماذج وتستدعي الواجهات مباشرة.
لا يُتاح محتوى المقترحات ولا تكاليف عروض الأسعار ولا قوائم العملاء. لا تُعرض هذه إلا في واجهة الإدارة.
لا تُتاح معلومات الموظفين. وحدة التدريب نفسها لا تخزّن أصلًا بيانات الهوية أو العنوان أو الراتب، بل رقم الموظف والمسمى الوظيفي فقط.
لا يُتاح التصدير بالجملة. إذا احتجت إلى بيانات تاريخية فراسلنا موضحًا الاستخدام المقصود.

هل تريد ربط البيانات، أو الاتصال المباشر من المتصفح، أو حقلًا غير موجود في هذه الصفحة؟ راسلنا عبر [email protected] موضحًا الاستخدام المقصود وعدد الاستدعاءات. استخدامك هذه الواجهة يعني قبول شروط الخدمة؛ وتجد تفاصيل معالجة البيانات في سياسة الخصوصية .