مرجع API

كل ما يفعله التطبيق يمر عبر واجهة API بصيغة JSON يمكنك استخدامها بمفتاح مؤسستك. والمرجع الكامل التفاعلي موجود على /api/docs، ومبني على /openapi.json.

تسلسل السجل الذي تتبعه مسارات واجهة API: المؤسسة، ثم المزرعة، ثم البيت المحمي، ثم الخط، ثم الدورة الزراعية. — تتبع مسارات السجل التسلسل من المؤسسة نزولًا إلى الدورة الزراعية.

المصادقة

curl -H "X-API-Key: dl_…" https://your-deepleaf-address/api/organizations/org-1
curl -H "Authorization: Bearer dl_…" https://your-deepleaf-address/api/organizations/org-1

يحصل المفتاح المفقود أو غير المعروف أو الملغى على 401. ويعيد المسار التابع لمؤسسة أخرى 404. ويحصل مفتاح العضو على 403 في إدارة المفاتيح ومدفوعات الفوترة؛ راجع المؤسسة والمفاتيح. واستخدم العنوان الذي تفتح عليه التطبيق.

اختصار المسارات

فيما يلي، يرمز {cycle} إلى المسار الكامل للدورة الزراعية:

/api/organizations/{organization_id}/farms/{farm_id}/greenhouses/{greenhouse_id}/rows/{row_id}/cycles/{cycle_id}

تُكتب الأسابيع بصيغة 2026-W40 أو بأي تاريخ في ذلك الأسبوع بصيغة YYYY-MM-DD.

التحليل

الطريقة والمسار	ما يفعله
`POST /api/observations`	يرفع صورة أو فيديو (حقل multipart باسم `file`، مع الحقول الاختيارية `mode` و`conf` و`sample_seconds` و`max_frames` و`mm_per_pixel`). ويعيد معرّف مهمة.
`GET /api/observations/{id}`	الحالة والتقدم والنتيجة، مع الإطارات والثمار والسيقان والنباتات و`quality`.
`GET /api/observations/{id}/frames/{frame}/{name}`	صورة إطار أو طبقتها.
`POST /api/examples/{key}`	يحلّل إحدى الصور النموذجية.
`POST {cycle}/videos`	يرفع جولة ويحفظها في دورة وأسبوع (`week`).
`POST {cycle}/videos/batch`	حتى 12 مقطع فيديو في حقول `files` متكررة، بترتيب المشي، تُحلَّل وتُحتسب جولة واحدة. ويعرض الحقل `clips` في المهمة تقدّم كل مقطع.

السجل

الطريقة والمسار	ما يفعله
`GET /api/organizations/{org}`	شجرة المزارع والبيوت المحمية والخطوط والدورات في المؤسسة.
`POST …/farms`، `…/greenhouses`، `…/rows`، `…/cycles`	ينشئ مستوى.
`PATCH` على مسار المستوى	يغيّر الأسماء والتفاصيل. وتبقى المعرّفات كما هي.
`GET` على مسار المستوى `+ /contents`	أعداد كل ما تحت المستوى.
`DELETE` على مسار المستوى	409 مع الأعداد ما دام يحتوي على أي شيء. ويحذفه `?cascade=true` مع محتواه.

السجلات

الطريقة والمسار	ما يفعله
`POST / GET {cycle}/harvests`	يسجّل حصادًا واحدًا (`week`، `kg`، `note`)، أو يعرض قائمتها. ويصفّي `?week=` النتائج.
`POST {cycle}/harvests/csv`	يرفع ملفًا بصيغة `week,kg[,note]`.
`PATCH / DELETE {cycle}/harvests/{id}`	يعدّل حصادًا واحدًا أو يحذفه.
`POST / GET {cycle}/irrigation`	يسجّل إدخالًا واحدًا، أو يعرض القائمة من الأحدث إلى الأقدم.
`PATCH / DELETE {cycle}/irrigation/{id}`	يعدّل إدخالًا واحدًا أو يحذفه.
`POST / GET {cycle}/climate`	يضيف قراءات بصيغة `{"points": [...]}`، أو يعرض قائمتها (`metric`، `from`، `to`، `limit`، `offset`).
`POST {cycle}/climate/csv/preview`	يفحص ملف مناخ دون تخزينه: الصيغة المكتشفة، ومقياس كل عمود ووحدته وتحويله ودرجة الثقة فيه، والمنطقة الزمنية والفترة الزمنية، والصفوف الأولى، والتحذيرات (`warnings`) والمشكلات المانعة (`problems`)، ومطابقة (`mapping`) للتأكيد. ويقبل حقول النموذج نفسها التي يقبلها الرفع، ومنها `compartment` و`date_order` (`dmy` أو `mdy`).
`POST {cycle}/climate/csv`	يرفع ملف مناخ. أرسل `mapping` من المعاينة لاستيراد ما عوين بالضبط (والأعمدة غير المذكورة فيها لا تُستورد)، أو `columns` لتسمية الأعمدة بنفسك. ويُرفض بالرمز 400 ما دامت في الملف مشكلات، وبالرمز 413 إذا تجاوز الحد الأقصى للحجم.
`POST {cycle}/climate/file/preview`	يفحص تصديرًا من حاسوب المناخ (CSV أو نص أو `.xlsx`) دون حفظه: الملف، والساعة التي يُقرأ بها (`time_zone`)، وكل عمود مع قياسه ووحدته، والقيم المضبوطة، والساعات الأولى، وما حُفظ مسبقًا، و`warnings`، و`problems` المانعة، و`mapping` للتأكيد.
`POST {cycle}/climate/file`	يحفظ ساعات التصدير بحسب `mapping` المؤكَّد؛ ويحفظ `remember` اختيارات الأعمدة للدفيئة. الساعات المستوردة مجددًا تُحدَّث ولا تتكرر أبدًا.
`POST {cycle}/climate/ingest`	الاستيراد نفسه لبرنامج نصي خاص بك: الملف في متن الطلب، والمفتاح في ترويسة فقط، واختيارات الأعمدة المحفوظة للدفيئة. راجع استيراد بيانات حاسوب المناخ.
`GET / DELETE {greenhouse}/climate/file-mapping`	اختيارات الأعمدة المحفوظة لدفيئة، أو نسيانها.
`GET {cycle}/climate/imports`	عمليات استيراد المناخ الأخيرة للدورة، من الأحدث إلى الأقدم.
`POST {cycle}/climate/imports/{id}/undo`	يتراجع عن استيراد واحد: يحذف القراءات التي أضافها ويستعيد القيم التي غيّرها. `409` إذا غيّر استيراد لاحق القراءات نفسها، إلا مع `{"confirm": true}`.
`PATCH / DELETE {cycle}/climate/{id}`	يعدّل قراءة واحدة أو يحذفها.
`POST {cycle}/fruit-mass`	غرامات مُدخلة لـ `green_g` و`turning_g` و`red_g`.
`POST {cycle}/weather`	يحدّث الطقس الخارجي لموقع البيت المحمي فورًا (`past_days`، `forecast_days`).

الأسابيع والتوقعات

الطريقة والمسار	ما يفعله
`GET {cycle}/weeks/{week}`	قراءة الأسبوع: أعداد الجولة، والحصاد، والري، والمناخ، وإنتاجية المياه، والتوقعات.
`GET {cycle}/forecast?week=`	التوقعات لأسبوع الجولة وللأسابيع السبعة التالية (افتراضيًا: أسبوع آخر جولة).
`POST / GET {cycle}/forecasts`	يصدر التوقعات الحالية ويحفظها، أو يعرض التوقعات المحفوظة مع الحصاد المسجّل منذ ذلك الحين.
`GET {cycle}/backtest`	الخطأ المعاد تشغيله لكل أفق مقابل الحصاد.
`GET {cycle}/export.csv`	صف واحد لكل أسبوع.

تصحيحات الجولات

فيما يلي، يرمز {walk} إلى /api/organizations/{org}/walks/{walk_id}، حيث walk_id هو معرّف مهمة الجولة. راجع صحّح جولة.

الطريقة والمسار	ما يفعله
`GET {walk}/corrections`	تصحيحات الجولة، وثمارها بعد التصحيح، وأسابيع الدورة الزراعية المحفوظة فيها، والأعداد `model` و`corrected`.
`POST {walk}/corrections`	يضيف تصحيحًا. قيمة `kind` هي `ripeness` (`track_id`، `ripeness`)، أو `remove` (`track_id`)، أو `add` (`ripeness`، `frame_id`، و`box` بصيغة `[x1, y1, x2, y2]` بالبكسل)، أو `counts` (`counts` مع `green` أو `turning` أو `red`). ويقبل كلٌّ منها `note` اختيارية.
`PATCH {walk}/corrections/{correction_id}`	يغيّر درجة النضج أو الإطار أو الأعداد أو الملاحظة. ويبقى النوع والثمرة كما هما.
`DELETE {walk}/corrections/{correction_id}`	يتراجع عن تصحيح واحد.

يحمل كل رد الأعداد model وcorrected للجولة. ويستطيع أي مفتاح للمؤسسة التصحيح، مفتاح مسؤول أو مفتاح عضو. وجولة مؤسسة أخرى تُرجع 404، والجولة التي ما زالت قيد التحليل تُرجع 409. والتصحيح الثاني على الثمرة نفسها، أو المجموعة الثانية من الأعداد، أو تجاوز 2,000 تصحيح في جولة واحدة، يُرجع 409. والأعداد أعداد صحيحة من 0 إلى 1,000,000، والملاحظة لا تتجاوز 500 حرف.

الجلسة والحالة

الطريقة والمسار	ما يفعله
`GET /api/health`	ما إذا كان التحليل وقاعدة البيانات متاحين. لا يحتاج إلى مفتاح.
`GET / POST / DELETE /api/session`	يقرأ الجلسة (مع دور المفتاح `role`)، أو يسجّل الدخول (ويضبط ملف تعريف الارتباط)، أو يسجّل الخروج.
`GET / POST /api/organizations/{org}/keys`	يعرض المفاتيح أو ينشئها. لمفاتيح المسؤول فقط، ويُعرض المفتاح الجديد مرة واحدة.
`PATCH …/keys/{id}`، `POST …/keys/{id}/revoke`	يغيّر اسم مفتاح أو يلغيه. ويحصل آخر مفتاح مسؤول على 409.