الصور والمرفقات واستيراد الجداول

تجمع هذه الصفحة أدوات الملفات: صور المنتجات ومرفقاتها، ومرفقات الشركات المصنعة، وشعار المؤسسة وختمها وتوقيعك الشخصي. وفيها أيضا sheet_import، الأداة التي تحول جدول بيانات إلى سجلات.

لا يمر الملف عبر استدعاء الأداة. كل رفع خطوتان: أداة البدء، مثل product_photo_upload_url_create، تتحقق من السجل ومن الملف المعلن وتعيد رابط رفع مؤقتا upload_url، فترسل إليه محتوى الملف مباشرة بطلب PUT، من المتصفح أو من أي برنامج. ثم تتحقق أداة الإنهاء المقابلة، مثل product_photo_upload_finalize، من حجم الملف ونوعه الفعلي، وتعالج الصورة عند الحاجة، وتحفظ الملف على سجله. لذلك لا يحد حجم الطلب الملف، ولا يمر محتواه في سياق الوكيل.

const blob = await (await fetch(SOURCE_URL)).blob();
await fetch(upload_url, { method: "PUT", headers: { "Content-Type": blob.type }, body: blob });

والملف الذي تحتفظ به المنصة أصلا، كملف أرسل إلى المساعد على واتساب، لا يرفع: أرسل مرجعه في الحقل staged_ref إلى أداة البدء، فينسخ إلى مكانه داخل الخادم، ثم استدع أداة الإنهاء مباشرة. وبهذا يحفظ كتالوج كامل حتى 100 ميغابايت.

صور المنتجات

تظهر صور المنتج في قائمة المنتجات وفي عروض الأسعار المطبوعة للبنود المربوطة به. وللتفاصيل في التطبيق راجع الصور والملفات.

product_photo_list

يعرض صور منتج، لكل صورة path ورابط مؤقت لمشاهدتها. استخدمه لتعرف path الذي تحتاجه product_photo_delete، فأداة `products_get` تعيد الروابط وحدها.

للقراءة فقط · الصلاحية products.read · كل الأدوار · الخطة الاحترافية وخطة المؤسسات

ما يعيده: قائمة أزواج {path, url}، زوج لكل صورة، والرابط url صالح لنحو ساعة. والمنتج بلا صور يعيد قائمة فارغة.

• المنتج الذي لا تملكه مؤسستك أو الموجود في سلة المهملات يرد بـ404.

product_photo_upload_url_create

يبدأ إضافة صورة إلى منتج في الكتالوج: يتحقق من المنتج ومن الملف المعلن، ثم يعيد رابط رفع مؤقتا ترسل إليه الصورة مباشرة بطلب PUT. وبعد الرفع استدع product_photo_upload_finalize. وكل صورة تضاف دون أن تستبدل غيرها.

يغير البيانات · الصلاحية products.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

{
  "id": 1187,
  "filename": "syringe-10ml-front.jpg",
  "content_type": "image/jpeg",
  "size_bytes": 482113
}

ما يعيده: upload_id وupload_url وmethod (PUT) وheaders وexpires_at (الحالة 201). ومع staged_ref يعود upload_url فارغا وstaged: true.

• الحد الأقصى 5 ميغابايت. والمنتج الذي لا تملكه مؤسستك أو الموجود في سلة المهملات يرد بـ404.
• الرابط لرفع واحد، وينتهي عند expires_at بعد ساعتين من إنشائه. ولا يحفظ شيء قبل أداة الإنهاء، والرفع الذي لا ينهى خلال 24 ساعة يحذف مع ملفه.
• النوع غير المدعوم يرد بـ400، والحجم المعلن الأكبر من الحد يرد بـ413، ولا ينشأ رابط في الحالتين.
• تستطيع كل مؤسسة، بكل مفاتيحها وموصلاتها معا، أن تفتح 20 رفعا في الوقت نفسه على الأكثر (بدأ ولم يكتمل ورابطه لم ينته)، وأن تبدأ 500 رفع في اليوم على الأكثر بتوقيت UTC، ما لم تحدد بروكداك للمؤسسة حدودا أخرى. وإذا بلغت أحد الحدين ردت أداة البدء بـ429 مع code: "upload_limit_reached" وretry_after_seconds، فأكمل بأداة الإنهاء الرفوع التي أرسلت ملفاتها، أو انتظر تلك المدة. والرابط الذي لم يستعمل يترك مكانه حين ينتهي.

product_photo_upload_finalize

ينهي رفعا بدأته product_photo_upload_url_create: يتحقق من حجم الصورة ونوعها الفعلي، ويحول صيغتها أو يقص حوافها أو يصغرها عند الحاجة، ثم يضيفها إلى المنتج.

يغير البيانات · الصلاحية products.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

{
  "upload_id": "5b0f3c1e-8a4d-4f6b-9e2a-7c1d3e5f9a02",
  "trim_whitespace": true,
  "max_width": 1600
}

ما يعيده: path وurl للصورة الجديدة، والرابط صالح لنحو ساعة، وcontent_type وsize_bytes وwidth وheight، وconverted_from حين حولت الصيغة، وtrimmed وresized. احتفظ بـpath لتحذف الصورة أو تنسخها لاحقا.

• الصورة بصيغة خارج المسموح، مثل AVIF أو TIFF، تحول إلى JPEG بجودة 85، أو إلى PNG إن كانت فيها شفافية. والصورة التي لا تحتاج تحويلا ولا قصا ولا تصغيرا تحفظ كما رفعت. ولا تقبل صور HEIC، فصدرها بصيغة JPEG أو PNG.
• يقرأ الخادم الملف نفسه ولا يثق بالنوع المعلن: الملف الذي لا يطابق نوعا مقبولا أو يتجاوز الحد يحذف ويرد بـ422 أو 413 مع السبب، فابدأ رفعا جديدا.
• ينهى كل upload_id مرة واحدة. والمعرف المجهول أو التابع لمؤسسة أخرى يرد بـ404، والمنتهي يرد بـ410، والمستعمل سابقا يرد بـ409.
• إن استدعيت الإنهاء قبل الرفع رد بـ409 دون أن يضيع الرفع: ارفع الملف إلى upload_url ثم استدعه ثانية.

product_photo_delete

يحذف صورة واحدة من منتج حذفا نهائيا. ولا يمكن التراجع عنه.

يحذف بيانات أو يستبدلها · الصلاحية products.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

ما يعيده: تأكيد الحذف (success: true).

• المسار الذي ليس من صور هذا المنتج يرد بـ400، والمنتج الذي لا تملكه مؤسستك يرد بـ404.

مرفقات المنتجات

تحفظ مستندات المنتج في ثلاث فئات: sfda_cert وcatalog وother. وقائمة المرفقات مع مساراتها تعيدها `products_get` في المصفوفة attachments.

product_attachment_upload_url_create

يبدأ حفظ مستند على منتج في الكتالوج: شهادة هيئة الغذاء والدواء (SFDA) أو الكتالوج أو ملفا آخر. يعيد رابط رفع مؤقتا ترسل إليه الملف بطلب PUT، أو ينسخ ملفا تحتفظ به المنصة أصلا إن أرسلت staged_ref. ثم استدع product_attachment_upload_finalize.

يغير البيانات · الصلاحية products.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

{
  "id": 1187,
  "category": "catalog",
  "filename": "syringe-catalog-2026.pdf",
  "content_type": "application/pdf",
  "size_bytes": 2864117
}

ما يعيده: upload_id وupload_url وmethod (PUT) وheaders وexpires_at (الحالة 201). ومع staged_ref يعود upload_url فارغا وstaged: true.

• الحد 15 ميغابايت للملف المرفوع، و100 ميغابايت للملف المرجعي. والمنتج الذي لا تملكه مؤسستك أو الموجود في سلة المهملات يرد بـ404.
• الرابط لرفع واحد، وينتهي عند expires_at بعد ساعتين من إنشائه. ولا يحفظ شيء قبل أداة الإنهاء، والرفع الذي لا ينهى خلال 24 ساعة يحذف مع ملفه.
• النوع غير المدعوم يرد بـ400، والحجم المعلن الأكبر من الحد يرد بـ413، ولا ينشأ رابط في الحالتين.
• تستطيع كل مؤسسة، بكل مفاتيحها وموصلاتها معا، أن تفتح 20 رفعا في الوقت نفسه على الأكثر (بدأ ولم يكتمل ورابطه لم ينته)، وأن تبدأ 500 رفع في اليوم على الأكثر بتوقيت UTC، ما لم تحدد بروكداك للمؤسسة حدودا أخرى. وإذا بلغت أحد الحدين ردت أداة البدء بـ429 مع code: "upload_limit_reached" وretry_after_seconds، فأكمل بأداة الإنهاء الرفوع التي أرسلت ملفاتها، أو انتظر تلك المدة. والرابط الذي لم يستعمل يترك مكانه حين ينتهي.

product_attachment_upload_finalize

ينهي رفعا بدأته product_attachment_upload_url_create: يتحقق من حجم الملف ونوعه الفعلي، ثم يحفظه على المنتج في الفئة التي اخترتها عند البدء.

يغير البيانات · الصلاحية products.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

{
  "upload_id": "0e7b2d94-3c51-4a8f-b6d2-9f4e1a7c3b58"
}

ما يعيده: path وurl وname للمرفق الجديد، والرابط صالح لنحو ساعة، وcontent_type وsize_bytes. ويحفظ الملف بالنوع الذي تثبته محتوياته.

• يستعمل المرجع staged_ref مرة واحدة: بعد نجاح الإنهاء تحذف النسخة المحتجزة، وإن رفض الملف عاد المرجع صالحا لمحاولة ثانية.
• يقرأ الخادم الملف نفسه ولا يثق بالنوع المعلن: الملف الذي لا يطابق نوعا مقبولا أو يتجاوز الحد يحذف ويرد بـ422 أو 413 مع السبب، فابدأ رفعا جديدا.
• ينهى كل upload_id مرة واحدة. والمعرف المجهول أو التابع لمؤسسة أخرى يرد بـ404، والمنتهي يرد بـ410، والمستعمل سابقا يرد بـ409.
• إن استدعيت الإنهاء قبل الرفع رد بـ409 دون أن يضيع الرفع: ارفع الملف إلى upload_url ثم استدعه ثانية.

product_attachment_delete

يحذف مرفقا واحدا من منتج حذفا نهائيا. ولا يمكن التراجع عنه.

يحذف بيانات أو يستبدلها · الصلاحية products.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

{
  "id": 1187,
  "category": "catalog",
  "path": "9b2f1c0e-4d1a-4f6e-8c1b-3a7d5e2f9a10/products/1187/attachments/catalog/1791281700000-k3x9ab__syringe-catalog-2026.pdf"
}

ما يعيده: تأكيد الحذف (success: true).

• المسار الذي ليس في مجلد هذه الفئة من مرفقات المنتج يرد بـ400، والمنتج الذي لا تملكه مؤسستك يرد بـ404.

product_files_copy

يضع صورة منتج أو مرفقه على منتجات أخرى في مؤسستك بنسخة داخل التخزين، بالتكلفة نفسها مهما كان حجم الملف. ارفع النشرة التي تغطي عدة منتجات مرة واحدة، ثم انسخها هنا بدل رفعها لكل منتج. ولكل منتج نسخته، فحذفها من منتج لا يمس الآخرين.

يغير البيانات · الصلاحية products.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

{
  "kind": "catalog",
  "source_product_id": 1187,
  "path": "9b2f1c0e-4d1a-4f6e-8c1b-3a7d5e2f9a10/products/1187/attachments/catalog/1791281700000-k3x9ab__syringe-catalog-2026.pdf",
  "product_ids": [
    1188,
    1189,
    1190
  ]
}

ما يعيده: كائن فيه copied (لكل منتج product_id والمسار الجديد path) وfailed (لكل منتج product_id وسبب الإخفاق error).

• المسار الذي ليس في مجلد هذا النوع من ملفات المنتج المصدر يرد بـ400، وأي منتج لا تملكه مؤسستك أو محذوف يرد بـ404 ولا ينسخ شيء. وإخفاق نسخة واحدة لا يوقف الباقي، فأعد المحاولة للمنتجات الواردة في failed وحدها.

مرفقات الشركات المصنعة

لكل شركة مصنعة أربع فئات من المرفقات: catalog وsfda_ar وiso وauthorization. وتشرح مرفقات الشركة كيف تستعمل في التطبيق.

manufacturer_attachment_list

يعرض كل الملفات المحفوظة على شركة مصنعة في فئاتها الأربع، لكل ملف مساره واسمه وحجمه ورابط تنزيل مؤقت.

للقراءة فقط · الصلاحية manufacturers.read · كل الأدوار · الخطة الاحترافية وخطة المؤسسات

ما يعيده: قائمة المرفقات، لكل مرفق category وpath وname وsize وuploaded_at وurl، والرابط صالح لنحو ساعة.

• الشركة المصنعة التي لا تملكها مؤسستك ترد بـ404.

manufacturer_attachment_upload_url_create

يبدأ حفظ مستند على شركة مصنعة: كتالوجها أو ترخيص ممثلها المعتمد لدى هيئة الغذاء والدواء (SFDA) أو شهادة ISO أو خطاب التفويض الذي تحمله مؤسستك منها. يعيد رابط رفع مؤقتا، أو ينسخ ملفا تحتفظ به المنصة إن أرسلت staged_ref، وبه يحفظ كتالوج المورد الكامل. ثم استدع manufacturer_attachment_upload_finalize.

يغير البيانات · الصلاحية manufacturers.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

{
  "id": 214,
  "category": "catalog",
  "staged_ref": "wa-staged:3f9a1c52-7b1e-4d2a-9c61-5e0b2d7a8f14",
  "filename": "meditech-catalog-2026.pdf"
}

ما يعيده: upload_id وupload_url وmethod (PUT) وheaders وexpires_at (الحالة 201). ومع staged_ref يعود upload_url فارغا وstaged: true.

• الحد 15 ميغابايت للملف المرفوع، و100 ميغابايت للملف المرجعي. والشركة المصنعة التي لا تملكها مؤسستك ترد بـ404.
• الرابط لرفع واحد، وينتهي عند expires_at بعد ساعتين من إنشائه. ولا يحفظ شيء قبل أداة الإنهاء، والرفع الذي لا ينهى خلال 24 ساعة يحذف مع ملفه.
• النوع غير المدعوم يرد بـ400، والحجم المعلن الأكبر من الحد يرد بـ413، ولا ينشأ رابط في الحالتين.
• تستطيع كل مؤسسة، بكل مفاتيحها وموصلاتها معا، أن تفتح 20 رفعا في الوقت نفسه على الأكثر (بدأ ولم يكتمل ورابطه لم ينته)، وأن تبدأ 500 رفع في اليوم على الأكثر بتوقيت UTC، ما لم تحدد بروكداك للمؤسسة حدودا أخرى. وإذا بلغت أحد الحدين ردت أداة البدء بـ429 مع code: "upload_limit_reached" وretry_after_seconds، فأكمل بأداة الإنهاء الرفوع التي أرسلت ملفاتها، أو انتظر تلك المدة. والرابط الذي لم يستعمل يترك مكانه حين ينتهي.

manufacturer_attachment_upload_finalize

ينهي رفعا بدأته manufacturer_attachment_upload_url_create: يتحقق من حجم الملف ونوعه الفعلي، ثم يحفظه على الشركة المصنعة في الفئة التي اخترتها عند البدء.

يغير البيانات · الصلاحية manufacturers.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

{
  "upload_id": "a41c9e27-6d03-4b8e-8f15-2c7a9b0d4e61"
}

ما يعيده: path وurl وname للمرفق الجديد، والرابط صالح لنحو ساعة، وcontent_type وsize_bytes.

• يستعمل المرجع staged_ref مرة واحدة: بعد نجاح الإنهاء تحذف النسخة المحتجزة، وإن رفض الملف عاد المرجع صالحا لمحاولة ثانية.
• يقرأ الخادم الملف نفسه ولا يثق بالنوع المعلن: الملف الذي لا يطابق نوعا مقبولا أو يتجاوز الحد يحذف ويرد بـ422 أو 413 مع السبب، فابدأ رفعا جديدا.
• ينهى كل upload_id مرة واحدة. والمعرف المجهول أو التابع لمؤسسة أخرى يرد بـ404، والمنتهي يرد بـ410، والمستعمل سابقا يرد بـ409.
• إن استدعيت الإنهاء قبل الرفع رد بـ409 دون أن يضيع الرفع: ارفع الملف إلى upload_url ثم استدعه ثانية.

manufacturer_attachment_delete

يحذف مرفقا واحدا من شركة مصنعة حذفا نهائيا. ولا يمكن التراجع عنه.

يحذف بيانات أو يستبدلها · الصلاحية manufacturers.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

{
  "id": 214,
  "category": "iso",
  "path": "9b2f1c0e-4d1a-4f6e-8c1b-3a7d5e2f9a10/manufacturers/214/attachments/iso/1791281700000-p7q2cd__iso-13485-certificate.pdf"
}

ما يعيده: تأكيد الحذف (success: true).

• المسار الذي ليس بين مرفقات هذه الشركة في الفئة المذكورة يرد بـ400، والشركة التي لا تملكها مؤسستك ترد بـ404.

مستندات أمر البيع

يحتفظ أمر البيع بمستنداته، وأولها أمر شراء العميل بصيغة PDF. ترفع بالأداتين نفسيهما لكل رفع: بدء ثم إنهاء. وتعرض المستندات في documents ضمن `sales_orders_get`.

sales_order_document_upload_url_create

يبدأ حفظ مستند على أمر بيع: أمر شراء العميل بصيغة PDF أو صورة ممسوحة منه أو نسخة معدلة. يعيد رابط رفع مؤقتا، أو ينسخ ملفا تحتفظ به المنصة إن أرسلت staged_ref. ثم استدع sales_order_document_upload_finalize.

يغير البيانات · الصلاحية orders.write · الأدوار: المالك، المدير، المبيعات · الخطة الاحترافية وخطة المؤسسات

{
  "id": 1042,
  "filename": "NUPCO-PO-4300010571.pdf",
  "content_type": "application/pdf",
  "size_bytes": 108281
}

ما يعيده: upload_id وupload_url وmethod (PUT) وheaders وexpires_at (الحالة 201). ومع staged_ref يعود upload_url فارغا وstaged: true.

• الحد 15 ميغابايت للملف المرفوع، و100 ميغابايت للملف المرجعي. ويحتفظ الأمر بأي عدد من المستندات. والأمر الذي لا تملكه مؤسستك يرد بـ404.
• الرابط لرفع واحد، وينتهي عند expires_at بعد ساعتين من إنشائه. ولا يحفظ شيء قبل أداة الإنهاء، والرفع الذي لا ينهى خلال 24 ساعة يحذف مع ملفه.
• النوع غير المدعوم يرد بـ400، والحجم المعلن الأكبر من الحد يرد بـ413، ولا ينشأ رابط في الحالتين.
• تستطيع كل مؤسسة، بكل مفاتيحها وموصلاتها معا، أن تفتح 20 رفعا في الوقت نفسه على الأكثر (بدأ ولم يكتمل ورابطه لم ينته)، وأن تبدأ 500 رفع في اليوم على الأكثر بتوقيت UTC، ما لم تحدد بروكداك للمؤسسة حدودا أخرى. وإذا بلغت أحد الحدين ردت أداة البدء بـ429 مع code: "upload_limit_reached" وretry_after_seconds، فأكمل بأداة الإنهاء الرفوع التي أرسلت ملفاتها، أو انتظر تلك المدة. والرابط الذي لم يستعمل يترك مكانه حين ينتهي.

sales_order_document_upload_finalize

ينهي رفعا بدأته sales_order_document_upload_url_create: يتحقق من حجم الملف ونوعه الفعلي، ثم يحفظه على أمر البيع.

يغير البيانات · الصلاحية orders.write · الأدوار: المالك، المدير، المبيعات · الخطة الاحترافية وخطة المؤسسات

{
  "upload_id": "a41c9e27-6d03-4b8e-8f15-2c7a9b0d4e61"
}

ما يعيده: path وurl وname للمستند الجديد، والرابط صالح لنحو ساعة، وcontent_type وsize_bytes.

• يقرأ الخادم الملف نفسه ولا يثق بالنوع المعلن: الملف الذي لا يطابق نوعا مقبولا أو يتجاوز الحد يحذف ويرد بـ422 أو 413 مع السبب، فابدأ رفعا جديدا.
• ينهى كل upload_id مرة واحدة. والمعرف المجهول أو التابع لمؤسسة أخرى يرد بـ404، والمنتهي يرد بـ410، والمستعمل سابقا يرد بـ409.
• إن استدعيت الإنهاء قبل الرفع رد بـ409 دون أن يضيع الرفع: ارفع الملف إلى upload_url ثم استدعه ثانية.

sales_order_document_delete

يحذف مستندا واحدا من أمر بيع حذفا نهائيا. ولا يمكن التراجع عنه.

يحذف بيانات أو يستبدلها · الصلاحية orders.write · الأدوار: المالك، المدير، المبيعات · الخطة الاحترافية وخطة المؤسسات

{
  "id": 1042,
  "path": "9b2f1c0e-4d1a-4f6e-8c1b-3a7d5e2f9a10/sales-orders/1042/documents/1791281700000-p7q2cd__NUPCO-PO-4300010571.pdf"
}

ما يعيده: تأكيد الحذف (success: true).

• المسار الذي ليس بين مستندات هذا الأمر يرد بـ400، والأمر الذي لا تملكه مؤسستك يرد بـ404.

الشعار والختم والتوقيع

ثلاث صور تطبع على عروض الأسعار. الشعار والختم للمؤسسة ولا يغيرهما إلا المالك، والتوقيع شخصي يديره العضو الذي يعمل الاتصال باسمه. والرفع يستبدل الصورة السابقة دائما.

settings_logo_upload_url_create

يبدأ ضبط شعار المؤسسة الذي يطبع في ترويسة ملفات PDF لعروض الأسعار، ويستبدل الشعار السابق عند الإنهاء. يعيد رابط رفع مؤقتا ترسل إليه الصورة بطلب PUT، ثم استدع settings_logo_upload_finalize.

يغير البيانات · الصلاحية settings.write · الأدوار: المالك · الخطة الاحترافية وخطة المؤسسات

{
  "filename": "acme-logo.png",
  "content_type": "image/png",
  "size_bytes": 48210
}

ما يعيده: upload_id وupload_url وmethod (PUT) وheaders وexpires_at (الحالة 201). ومع staged_ref يعود upload_url فارغا وstaged: true.

• الحد الأقصى 2 ميغابايت. والاتصال الذي لا يعود لمالك المؤسسة يرد بـ403.
• الرابط لرفع واحد، وينتهي عند expires_at بعد ساعتين من إنشائه. ولا يحفظ شيء قبل أداة الإنهاء، والرفع الذي لا ينهى خلال 24 ساعة يحذف مع ملفه.
• النوع غير المدعوم يرد بـ400، والحجم المعلن الأكبر من الحد يرد بـ413، ولا ينشأ رابط في الحالتين.
• تستطيع كل مؤسسة، بكل مفاتيحها وموصلاتها معا، أن تفتح 20 رفعا في الوقت نفسه على الأكثر (بدأ ولم يكتمل ورابطه لم ينته)، وأن تبدأ 500 رفع في اليوم على الأكثر بتوقيت UTC، ما لم تحدد بروكداك للمؤسسة حدودا أخرى. وإذا بلغت أحد الحدين ردت أداة البدء بـ429 مع code: "upload_limit_reached" وretry_after_seconds، فأكمل بأداة الإنهاء الرفوع التي أرسلت ملفاتها، أو انتظر تلك المدة. والرابط الذي لم يستعمل يترك مكانه حين ينتهي.

settings_logo_upload_finalize

ينهي رفعا بدأته settings_logo_upload_url_create: يتحقق من الصورة، ويحول صيغتها أو يقص حوافها أو يصغرها عند الحاجة، ثم يضبطها شعارا للمؤسسة مكان السابق.

يغير البيانات · الصلاحية settings.write · الأدوار: المالك · الخطة الاحترافية وخطة المؤسسات

{
  "upload_id": "c2d8f1a0-4b7e-4e39-a5c6-1f0b9d2e7a43",
  "trim_whitespace": true
}

ما يعيده: path وurl للصورة المحفوظة، والرابط صالح لنحو ساعة، وcontent_type وsize_bytes وwidth وheight، وconverted_from حين حولت الصيغة، وtrimmed وresized.

• صورة SVG تحفظ كما رفعت، فلا يغيرها trim_whitespace ولا max_width. وكثيرا ما يفيد trim_whitespace مع شعار أو ختم صدر بهامش واسع.
• الاتصال الذي لا يعود لمالك المؤسسة يرد بـ403.
• الصورة بصيغة خارج المسموح، مثل AVIF أو TIFF، تحول إلى JPEG بجودة 85، أو إلى PNG إن كانت فيها شفافية. والصورة التي لا تحتاج تحويلا ولا قصا ولا تصغيرا تحفظ كما رفعت. ولا تقبل صور HEIC، فصدرها بصيغة JPEG أو PNG.
• يقرأ الخادم الملف نفسه ولا يثق بالنوع المعلن: الملف الذي لا يطابق نوعا مقبولا أو يتجاوز الحد يحذف ويرد بـ422 أو 413 مع السبب، فابدأ رفعا جديدا.
• ينهى كل upload_id مرة واحدة. والمعرف المجهول أو التابع لمؤسسة أخرى يرد بـ404، والمنتهي يرد بـ410، والمستعمل سابقا يرد بـ409.
• إن استدعيت الإنهاء قبل الرفع رد بـ409 دون أن يضيع الرفع: ارفع الملف إلى upload_url ثم استدعه ثانية.

settings_logo_delete

يزيل شعار المؤسسة فتطبع ملفات PDF لعروض الأسعار بدونه. ولا يمكن التراجع عنه، وللاستعادة ارفع الشعار من جديد. للمالك وحده.

يحذف بيانات أو يستبدلها · الصلاحية settings.write · الأدوار: المالك · الخطة الاحترافية وخطة المؤسسات

لا معاملات.

ما يعيده: تأكيد الحذف (success: true).

settings_stamp_upload_url_create

يبدأ ضبط ختم المؤسسة الذي يطبع على ملفات PDF لعروض الأسعار، ويستبدل الختم السابق عند الإنهاء. يعيد رابط رفع مؤقتا ترسل إليه الصورة بطلب PUT، ثم استدع settings_stamp_upload_finalize.

يغير البيانات · الصلاحية settings.write · الأدوار: المالك · الخطة الاحترافية وخطة المؤسسات

{
  "filename": "acme-stamp.png",
  "content_type": "image/png",
  "size_bytes": 48210
}

ما يعيده: upload_id وupload_url وmethod (PUT) وheaders وexpires_at (الحالة 201). ومع staged_ref يعود upload_url فارغا وstaged: true.

• الحد الأقصى 2 ميغابايت. والاتصال الذي لا يعود لمالك المؤسسة يرد بـ403.
• الرابط لرفع واحد، وينتهي عند expires_at بعد ساعتين من إنشائه. ولا يحفظ شيء قبل أداة الإنهاء، والرفع الذي لا ينهى خلال 24 ساعة يحذف مع ملفه.
• النوع غير المدعوم يرد بـ400، والحجم المعلن الأكبر من الحد يرد بـ413، ولا ينشأ رابط في الحالتين.
• تستطيع كل مؤسسة، بكل مفاتيحها وموصلاتها معا، أن تفتح 20 رفعا في الوقت نفسه على الأكثر (بدأ ولم يكتمل ورابطه لم ينته)، وأن تبدأ 500 رفع في اليوم على الأكثر بتوقيت UTC، ما لم تحدد بروكداك للمؤسسة حدودا أخرى. وإذا بلغت أحد الحدين ردت أداة البدء بـ429 مع code: "upload_limit_reached" وretry_after_seconds، فأكمل بأداة الإنهاء الرفوع التي أرسلت ملفاتها، أو انتظر تلك المدة. والرابط الذي لم يستعمل يترك مكانه حين ينتهي.

settings_stamp_upload_finalize

ينهي رفعا بدأته settings_stamp_upload_url_create: يتحقق من الصورة، ويحول صيغتها أو يقص حوافها أو يصغرها عند الحاجة، ثم يضبطها ختما للمؤسسة مكان السابق.

يغير البيانات · الصلاحية settings.write · الأدوار: المالك · الخطة الاحترافية وخطة المؤسسات

{
  "upload_id": "c2d8f1a0-4b7e-4e39-a5c6-1f0b9d2e7a43",
  "trim_whitespace": true
}

ما يعيده: path وurl للصورة المحفوظة، والرابط صالح لنحو ساعة، وcontent_type وsize_bytes وwidth وheight، وconverted_from حين حولت الصيغة، وtrimmed وresized.

• صورة SVG تحفظ كما رفعت، فلا يغيرها trim_whitespace ولا max_width. وكثيرا ما يفيد trim_whitespace مع شعار أو ختم صدر بهامش واسع.
• الاتصال الذي لا يعود لمالك المؤسسة يرد بـ403.
• الصورة بصيغة خارج المسموح، مثل AVIF أو TIFF، تحول إلى JPEG بجودة 85، أو إلى PNG إن كانت فيها شفافية. والصورة التي لا تحتاج تحويلا ولا قصا ولا تصغيرا تحفظ كما رفعت. ولا تقبل صور HEIC، فصدرها بصيغة JPEG أو PNG.
• يقرأ الخادم الملف نفسه ولا يثق بالنوع المعلن: الملف الذي لا يطابق نوعا مقبولا أو يتجاوز الحد يحذف ويرد بـ422 أو 413 مع السبب، فابدأ رفعا جديدا.
• ينهى كل upload_id مرة واحدة. والمعرف المجهول أو التابع لمؤسسة أخرى يرد بـ404، والمنتهي يرد بـ410، والمستعمل سابقا يرد بـ409.
• إن استدعيت الإنهاء قبل الرفع رد بـ409 دون أن يضيع الرفع: ارفع الملف إلى upload_url ثم استدعه ثانية.

settings_stamp_delete

يزيل ختم المؤسسة فتطبع ملفات PDF لعروض الأسعار بدونه. ولا يمكن التراجع عنه، وللاستعادة ارفع الختم من جديد. للمالك وحده.

يحذف بيانات أو يستبدلها · الصلاحية settings.write · الأدوار: المالك · الخطة الاحترافية وخطة المؤسسات

لا معاملات.

ما يعيده: تأكيد الحذف (success: true).

settings_signature_get

يعيد صورة توقيع العضو الذي يعمل الاتصال باسمه، أو قيمتين null إن لم يحفظ له توقيع. والتوقيع ملك العضو لا المؤسسة.

للقراءة فقط · الصلاحية settings.read · كل الأدوار · الخطة الاحترافية وخطة المؤسسات

لا معاملات.

ما يعيده: path وurl للتوقيع، والرابط صالح لنحو ساعة، أو null للاثنين إن لم يوجد توقيع.

settings_signature_upload_url_create

يبدأ ضبط صورة توقيع العضو الذي يعمل الاتصال باسمه، وتطبع على عروض الأسعار المعتمدة التي يكون فيها مندوب المبيعات. ويستبدل التوقيع السابق عند الإنهاء. يعيد رابط رفع مؤقتا ترسل إليه الصورة بطلب PUT، ثم استدع settings_signature_upload_finalize.

يغير البيانات · الصلاحية settings.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

{
  "filename": "signature.png",
  "content_type": "image/png",
  "size_bytes": 48210
}

ما يعيده: upload_id وupload_url وmethod (PUT) وheaders وexpires_at (الحالة 201). ومع staged_ref يعود upload_url فارغا وstaged: true.

• الحد الأقصى 2 ميغابايت.
• الرابط لرفع واحد، وينتهي عند expires_at بعد ساعتين من إنشائه. ولا يحفظ شيء قبل أداة الإنهاء، والرفع الذي لا ينهى خلال 24 ساعة يحذف مع ملفه.
• النوع غير المدعوم يرد بـ400، والحجم المعلن الأكبر من الحد يرد بـ413، ولا ينشأ رابط في الحالتين.
• تستطيع كل مؤسسة، بكل مفاتيحها وموصلاتها معا، أن تفتح 20 رفعا في الوقت نفسه على الأكثر (بدأ ولم يكتمل ورابطه لم ينته)، وأن تبدأ 500 رفع في اليوم على الأكثر بتوقيت UTC، ما لم تحدد بروكداك للمؤسسة حدودا أخرى. وإذا بلغت أحد الحدين ردت أداة البدء بـ429 مع code: "upload_limit_reached" وretry_after_seconds، فأكمل بأداة الإنهاء الرفوع التي أرسلت ملفاتها، أو انتظر تلك المدة. والرابط الذي لم يستعمل يترك مكانه حين ينتهي.

settings_signature_upload_finalize

ينهي رفعا بدأته settings_signature_upload_url_create: يتحقق من الصورة، ويحول صيغتها أو يقص حوافها أو يصغرها عند الحاجة، ثم يضبطها توقيعا للعضو مكان السابق.

يغير البيانات · الصلاحية settings.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

{
  "upload_id": "c2d8f1a0-4b7e-4e39-a5c6-1f0b9d2e7a43",
  "trim_whitespace": true
}

ما يعيده: path وurl للصورة المحفوظة، والرابط صالح لنحو ساعة، وcontent_type وsize_bytes وwidth وheight، وconverted_from حين حولت الصيغة، وtrimmed وresized.

• يطبع التوقيع حين يكون مندوب المبيعات المربوط بعرض السعر عضوا في الفريق مرتبطا بحسابه في سجل مندوبي المبيعات، ولا يتوقف الاعتماد على وجود توقيع. والتوقيع المصور على ورق أبيض يحتاج عادة trim_whitespace.
• لا ينهي رفع التوقيع إلا العضو الذي بدأه.
• الصورة بصيغة خارج المسموح، مثل AVIF أو TIFF، تحول إلى JPEG بجودة 85، أو إلى PNG إن كانت فيها شفافية. والصورة التي لا تحتاج تحويلا ولا قصا ولا تصغيرا تحفظ كما رفعت. ولا تقبل صور HEIC، فصدرها بصيغة JPEG أو PNG.
• يقرأ الخادم الملف نفسه ولا يثق بالنوع المعلن: الملف الذي لا يطابق نوعا مقبولا أو يتجاوز الحد يحذف ويرد بـ422 أو 413 مع السبب، فابدأ رفعا جديدا.
• ينهى كل upload_id مرة واحدة. والمعرف المجهول أو التابع لمؤسسة أخرى يرد بـ404، والمنتهي يرد بـ410، والمستعمل سابقا يرد بـ409.
• إن استدعيت الإنهاء قبل الرفع رد بـ409 دون أن يضيع الرفع: ارفع الملف إلى upload_url ثم استدعه ثانية.

settings_signature_delete

يزيل توقيع العضو الذي يعمل الاتصال باسمه. فتطبع عروض الأسعار التي يكون مندوب المبيعات فيها بلا توقيع، ولا يتوقف الاعتماد على غيابه. ولا يمكن التراجع عنه.

يحذف بيانات أو يستبدلها · الصلاحية settings.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

لا معاملات.

ما يعيده: تأكيد الحذف (success: true).

الاستيراد من جدول بيانات

تقرأ sheet_import ملف Excel أو CSV على الخادم: تحدد أي عمود يعني ماذا من عينة صغيرة منه، ثم تقرأ كل الصفوف بنفسها، فتكلف ورقة من 2000 صف ما تكلفه ورقة من 70. ولها خمسة أهداف. tender_items تنشئ منافسة يدوية لمؤسستك ببنودها. وproducts تنشئ منتجات في الكتالوج وتربط كلا منها بالشركة المصنعة المذكورة في صفه، وتنشئ الشركة إن لم تكن موجودة. وquotation_items تنشئ عرض سعر واحدا، ويلزم لكل سطر فيه سعر من الملف، فالورقة بلا عمود أسعار تعود بالحالة needs_confirmation. وbid_pricing تسعر بنود منافسة موجودة بمطابقة رمز المادة. وmanufacturers تنشئ شركة لكل صف وتتخطى الأسماء الموجودة عندك وتسردها في skipped_existing. وقائمة قصيرة أو ملف PDF أو صورة لا تحتاج هذه الأداة: أنشئ السجلات بـ`tenders_create` أو `products_bulk_create` أو `quotations_create`.

sheet_import

ينشئ سجلات من ملف Excel أو CSV دون أن تقرأ صفوفه بنفسك. يحدد الخادم من عينة أي عمود يعني ماذا، ويطبق ذلك على كل صف، ثم يعيد الربط الذي استعمله. وإن لم يكن واثقا منه لم يكتب شيئا وأعاده لتؤكده.

يغير البيانات · الصلاحية tenders.write أو products.write أو quotations.write أو bids.write أو manufacturers.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

{
  "sheet_base64": "UEsDBBQABgAIAAAAIQBi7p1L...",
  "filename": "meditech-price-list.xlsx",
  "target": "products",
  "manufacturer_id": 214,
  "instruction": "The price column is the cost per carton; the prices are in USD",
  "constants": {
    "cost_currency": "USD"
  },
  "dry_run": true
}

ما يعيده: كائن فيه status (imported أو preview أو needs_confirmation) والربط المستعمل في mapping والأعمدة المتجاهلة وعدد الصفوف في counts وأول 20 مشكلة في issues مع أرقام صفوفها ومعاينة من 3 صفوف في preview وصيغة layout القابلة لإعادة الإرسال. وبعد الكتابة يضاف created، ومعه tender_id للمنافسة، وquotation_id وquote_number لعرض السعر، وpriced وunmatched للأسعار، وskipped_existing للشركات المصنعة. وللهدف products يعني own_headers: true أن الربط قرئ من العناوين، ويحمل attachments خطة الملفات: rows (صور كل صف photos وكتالوجاته catalogs، ومعها product_id بعد الاستيراد)، وproblems لكل صف وملف، وshared_catalogue_numbers، والملفات غير المستعملة unused.

• حالة needs_confirmation تعني أن الخادم غير واثق من قراءته للأعمدة، أو أن حقلا لازما بلا عمود، ولا يكتب شيئا. اعرض الربط على صاحب الملف بلغته، ثم أعد الاستدعاء مع confirm: true أو مع layout مصححة.
• لكل هدف صلاحيته: tender_items تحتاج tenders.write ودور المالك أو المدير، وproducts تحتاج products.write، وmanufacturers تحتاج manufacturers.write، وquotation_items تحتاج quotations.write، وbid_pricing تحتاج bids.write. وتصلح الأهداف الأربعة الأخيرة للمالك والمدير والمبيعات والمشتريات.
• تتخطى القراءة الصفوف الفارغة وسطور العناوين المكررة والشرائط المدمجة كإجمالي الصفحة والصفوف التي ينقصها حقل لازم، وتعدها بأسبابها في counts. وما جاوز سقف الهدف لا يكتب ويحسب في counts.truncated: 2000 صف لـtender_items وbid_pricing، و500 لـproducts وquotation_items وmanufacturers.
• في الهدف products يقبل كل حقل يعدله التطبيق للمنتج عمودا، ومعها Photo files و Catalog files. والورقة التي عناوينها هي عناوين الاستيراد نفسها، كالقالب من `products_import_template` أو مخرج `products_export_csv`، تقرأ أعمدتها من عناوينها دون خطوة التعرف. والعمود الذي يحمل قائمة يفصل بفاصلة منقوطة (;): رموز نوبكو وأولها الرئيسي، والشركات المصنعة، وأسماء الملفات.
• عمود Price per يقول ما يخصه السعران في الصف: Piece أو Unit للقطعة، أو Pack أو Box للعبوة، أو Carton أو Case للكرتون، أو Content لوحدة واحدة مما تحتويه القطعة، أو ما يقابلها بالعربية (قطعة ووحدة وعبوة وعلبة وكرتون ومحتوى)، أو اسم مستوى من الصف نفسه مثل Vial أو Kit. والخلية التي لا تسمي مستوى من الصف، أو تسمي مستوى لا عدد له فيه، تسقط المستوى والسعرين معا، ولكل منها مشكلة برقم صفها، لأن السعر بلا مستواه لا يعرف لأي وحدة هو. والخلية الفارغة تبقي المستوى غير محدد، فيستخدم السعران كما هما في كل بنود المنافسات. ويقرأ عمود Content unit وحدة المحتوى بأي من أسمائها (ml أو مل أو Tests)، والوحدة غير المعروفة تسقط خليتي المحتوى معا، ويقرأ عمود Product kind مفتاح النوع أو اسمه بالعربية أو الإنجليزية.
• إن رفضت الكتابة بسبب التعبئة رغم ذلك (price_basis_level_missing أو content_incomplete) فلا يكتب شيء، ويسمي الحقل rows كل صف مرفوض برقمه في الورقة row والحقل والإصلاح.
• لإرفاق الملفات بعد الاستيراد استعمل product_id في attachments.rows: `product_photo_upload_url_create` للصور، و`product_attachment_upload_url_create` بالفئة catalog للكتالوجات، ثم أداة الإنهاء المقابلة لكل منهما. والملف الذي تشترك فيه عدة صفوف ارفعه مرة ثم انسخه بـ`product_files_copy`.
• الأداة للجداول فقط. ملف PDF أو Word أو PowerPoint يرد بـ400، وملف xls القديم يرد بـ400 أيضا ويلزم حفظه بصيغة xlsx أو csv. وإنشاء المنتجات فوق حد خطتك يرد بـ403، وإنشاء عرض السعر يحتسب من حد الخطة الشهري لعروض الأسعار.