Logistivo CLI: أدِر عملياتك اللوجستية من الطرفية ومن نظام ERP لديك

كتالوج أوامر واحد يغذّي ثلاث واجهات: عميل الطرفية lg، ومساعد الذكاء الاصطناعي داخل لوحة التحكم، والقناة التي تتصل عبرها مساعدات الذكاء الاصطناعي الخارجية. تُكتب القدرة مرة واحدة وتظهر في الواجهات الثلاث — وأصبح لكل إجراء كتابة في لوحة التحكم أمرٌ مقابل، بحيث تستطيع نصوصك البرمجية ووكلاء الذكاء الاصطناعي الخاصون بك إنجاز العمل الذي يؤديه فريقك على الشاشة. أما المدفوعات والموافقة القانونية وإغلاق الحساب فتبقى في المتصفح عن قصد. هذه الصفحة عقد. جدول الأوامر أدناه ليس مكتوبًا يدويًا؛ بل يُولَّد من سجل الأوامر الحي مع كل طلب.

ما هو Logistivo CLI؟

Logistivo CLI (lg) عميل لسطر الأوامر ينفّذ أعمال حسابك في Logistivo — الشحنات والرحلات، والطلبات، والعروض والمناقصات، والأسطول والسائقين، والمستندات، وجهات الاتصال والحسابات الجارية، والفواتير والمحاسبة، والمستودع والمخزون، وأعضاء الفريق والتعريفات الجمركية — من الطرفية أو من نص برمجي أو من وكيل الذكاء الاصطناعي الخاص بك. الأوامر ليست مدمجة في العميل: إذ يجلب العميل كتالوج الأوامر من الخادم ويبني نفسه منه. ويمكن استدعاء الأوامر نفسها عبر HTTP دون تثبيت أي شيء — وهو المسار الذي تستخدمه تكاملات ERP و CRM — وكذلك عبر قناة MCP التي تتصل بها مساعدات الذكاء الاصطناعي الخارجية.

• شكل واحد لكل أمر: lg --parameter=value. يضم الكتالوج اليوم 519 أمرًا موزعة على مجالات (domains) عددها 125؛ وأوسع قائمة يراها دور واحد تضم 452 أمرًا في مجالات عددها 112.
• لكل إجراء كتابة في لوحة التحكم أمرٌ مقابل — فعند القياس مقابل نقاط نهاية الكتابة في اللوحة، تبيّن أن 100% من النقاط المشمولة بالنطاق مغطاة. أما المدفوعات (3D Secure) والموافقة القانونية وإغلاق الحساب فتبقى في المتصفح عن قصد؛ وفي هذه الحالات يعيد الأمر رابطًا بدلًا من ذلك.
• الأوامر التي تأخذ مستندًا أو صورة تعمل خارج المتصفح أيضًا: اكتب --attachment_uuid=@./cmr.pdf وسيرفع lg الملف أولًا؛ وعبر HTTP ترفع الملف إلى /api/common/commands:upload ثم تمرّر قيمة attachment_uuid المُعادة.
• تحمل مفاتيح التكامل مستوى وصول: employee (الافتراضي للمفاتيح الجديدة) للعمليات اليومية، و manager لشؤون الفريق والإعدادات والمفاتيح والمال. ولا يملك المفتاح أبدًا صلاحيات أكثر من الشخص الذي يعمل نيابةً عنه.
• الخيارات (flags) لا تُختلق أبدًا: كل خيار هو اسم معامل من JSON Schema الخاص بالأمر نفسه، وكذلك نوعه وما إذا كان إلزاميًا.
• أوامر الكتابة تطلب التأكيد؛ والأوامر غير القابلة للتراجع لا تعمل أبدًا من دونه (HTTP 409، ورمز الخروج 4 في CLI).
• إعادة المحاولة لا تُنشئ تكرارات: الاستدعاء الذي يحمل idempotency_key يُنفَّذ مرة واحدة على الأكثر.
• كل تنفيذ يُسجَّل في سجل تدقيق واحد — ومصدره مدوَّن: هل جاء من الطرفية أم من المحادثة أم من مساعد ذكاء اصطناعي.

ما المتاح اليوم، وما هو قادم

وُضع هذا القسم في أعلى الصفحة عن قصد. فأغلى خطأ يمكن أن ترتكبه وثيقة تكامل هو أن تصف نقطة نهاية (endpoint) لم تُفتح بعد كأنها متاحة: يكتب المطوّر المسؤول عن التكامل الشيفرة، فتُعيد نقطة النهاية 404، ولا تعود الثقة بعدها.

لأن العقد مُجمَّد، تظل شيفرة التكامل التي تكتبها اليوم تعمل مع افتتاح الأجزاء المتبقية. ويجب تجاهل الحقول التي لا تعرفها؛ فهذه القاعدة هي ما يتيح لنا الإضافة دون كسر أي شيء.

• كتالوج الأوامر وجدول الهوية — هوية كل أمر العامة (domain/verb) مُجمَّدة، ويُنشر إصدار العقد بالقيمة 1 في كل استجابة من الكتالوج وفي الترويسة X-Contract-Version. ويُولَّد الجدول في هذه الصفحة من السجل الحي: فالأمر المضاف على الخادم يظهر هنا تلقائيًا، والأمر المحذوف يختفي.
• نقطة نهاية للاستكشاف دون مصادقة — GET /api/public/cli/catalog — أسماء الأوامر، وهوية domain/verb، والوصف، ومعاملات JSON Schema، وأعلام البوابات، وحقول الإصدارات (since و deprecated_at و replaced_by و aliases). لا مصادقة: فإصدار رمز مميز (token) خطوة تأتي بعدَ قرار التكامل، لا قبله. ولا تحمل الاستجابة أي بيانات خاصة بالمستأجرين (tenants) على الإطلاق.
• نقاط نهاية الكتالوج والتنفيذ التي تتطلب مصادقة — GET /api/common/commands و GET /api/common/commands/{name} و POST /api/common/commands/{name}. وتقع بوابة الدور وبوابة التأكيد وعدم التكرار (idempotency) وسجل التدقيق في نقطة إنفاذ واحدة تمر عبرها المحادثة والطرفية أيضًا.
• تغطية لوحة التحكم: لكل إجراء كتابة أمرٌ مقابل — 519 أمرًا موزعة على مجالات عددها 125، جرى التحقق منها مقابل نقاط نهاية الكتابة في لوحة التحكم: كل نقطة نهاية مشمولة بالنطاق يقابلها أمر (نسخة مطابقة لنقطة النهاية أو الخدمة المشتركة نفسها)، ولا توجد نقطة غير مُثبتة. وخارج النطاق عن قصد: المدفوعات عبر 3D Secure، والموافقة القانونية، وإغلاق الحساب وتسجيل الدخول، وهي تبقى في المتصفح؛ وإدارة المفاتيح و webhooks وبيئة الاختبار (sandbox)، وهي أوامر مدمجة في lg؛ ونقاط النهاية الخاصة بتطبيق السائق.
• الفحص المسبق (dry_run): شاهد النتيجة دون تشغيل الأمر — عند وضع dry_run: true في جسم الطلب لا يُنفَّذ الأمر: بل يجري التحقق من الصحة، وبوابة الدور/النطاق (scope)، وتحديد الهدف، وحساب الرصيد، ثم تعود معاينة؛ لا يُكتب شيء، ولا يُستهلك أي رصيد، ولا يُستهلك مفتاح عدم التكرار. وتقبله نقطة نهاية الدفعات (batch) أيضًا، لكل دفعة. لا يدخل الفحص المسبق (preflight) أبدًا إلى معالج الأمر؛ وعند إطلاقه، لم تُنتج 178 عملية فحص مسبق شملت كل أوامر الكتابة في الكتالوج آنذاك أي عبارة كتابة واحدة.
• مفاتيح التكامل — مفاتيح API تعمل نيابةً عن عضو فعلي في الفريق، تُصدر من لوحة التحكم أو عبر lg keys create: نطاق قراءة/كتابة، ومستوى وصول (employee افتراضيًا، أو manager)، ومدة الصلاحية، وآخر استخدام، والتدوير، والنقل، والإلغاء. وعليها تقوم الأوامر lg login --api-key و lg whoami و lg logout الذي يُلغي المفتاح على الخادم.
• بيئة الاختبار (Sandbox) — جرّب عمليات الكتابة دون المساس ببيئة الإنتاج — مستأجر sandbox منفصل لكل شركة بكتالوج الأوامر نفسه؛ يُفتح بالخدمة الذاتية ويُصدر مفتاحه الخاص. والرصيد والسوق وتوجيه webhooks منفصلة بين البيئتين؛ وتُستنتج البيئة من شركة المفتاح ولا يمكن تمريرها مع الطلب.
• الإصدارات، وتصنيف الأخطاء، وعدم التكرار، وحدود المعدل — تحمل الأوامر الحقول since / deprecated_at / replaced_by / aliases، ويجيب الأمر المُهمَل (deprecated) بالترويسة X-Deprecated. وتحمل إخفاقات منطق الأعمال مفتاح error_key ثابتًا إلى جانب error_code على مستوى النقل، ويُنشر قاموس المفاتيح في الكتالوج. ومفاتيح عدم التكرار محصورة في شركتك، ومرتبطة بأمر واحد، ومقفلة لمدة 24 ساعة. وحدود المعدل (rate limits) لكل رمز مميز، في ثلاث فئات، وكل استجابة 429 تحمل Retry-After.
• Webhooks الصادرة: طلب POST عند وقوع حدث — الدفع (push) الموقَّع متاح الآن لـ 13 حدثًا. تُدار الاشتراكات من لوحة التحكم أو عبر lg webhooks؛ ويحمل التوقيع طابعه الزمني الخاص، وجدول إعادة المحاولة هو 60 · 300 · 1800 · 7200 · 21600 ثانية، ويُسجَّل سبب الكتم دائمًا. كل اسم حدث يقابله صنف حدث (event class) يُرسَل فعلًا — لا شيء يُعلَن عنه ثم لا يُرسل أبدًا. ولم يُلغَ مسار السحب (pull) القائم على updated_since + cursor: بل أُضيف الدفع إلى جانبه، لا بديلًا عنه.
• الأوامر التي تأخذ ملفات — يأخذ 33 أمرًا مستندًا أو صورة — CMR، أو فاتورة، أو رخصة تسجيل مركبة، أو صور منصّات نقّالة (pallets). ارفع الملف مرة واحدة إلى POST /api/common/commands:upload ، أو دع lg يتولى ذلك عبر --attachment_uuid=@./file.pdf ، ثم مرّر قيمة attachment_uuid المُعادة؛ أما عملاء MCP فيستخدمون الأداة upload_attachment. يُكتشف نوع الملف من محتواه، ويبقى الملف المرفوع صالحًا للاستخدام لمدة 24 ساعة.
• عميل الطرفية lg — منشور على npm بترخيص MIT: ثبّته بالأمر `npm install -g @lgstv/lg`، أو شغّله دون تثبيت عبر `npx @lgstv/lg`. وهو ملف واحد بلا أي تبعيات، ولأن واجهة HTTP مفتوحة يمكنك إجراء التكامل من دونه. يسجّل الدخول برمز موافقة تؤكّده في المتصفح ثم يبقى مسجّل الدخول، مجدّدًا جلسته بنفسه؛ ويرفع الملفات المحلية نيابةً عنك (@path و --file و lg upload)، ويدير مفاتيح التكامل (lg keys)، ولا يقبل أبدًا أي قيمة سرية في سطر الأوامر، ويحترم Retry-After، ويعيد محاولة أخطاء 5xx بمفتاح عدم التكرار نفسه، وينبّه عند استخدام أوامر مُهمَلة وعند صدور إصدارات أحدث من العقد.
• المزامنة التزايدية: ترقيم الصفحات بالمؤشر (cursor) و updated_since — العقد الموضح أدناه (limit + مؤشر cursor موقَّع ومُعتم، و next_cursor، و updated_since) ثابت، ويجري تعميمه على أوامر القوائم. وإلى أن يُعلن أمر قائمة ما عن cursor و updated_since في JSON Schema الخاص به، فتعامل معه كنافذة صغيرة: حد أقصى 20 صفًا، ولا مؤشر.

ما الذي يميّز هذا النهج: العميل لا يعرف أي أوامر، بل يبنيها من الكتالوج

هذا هو القرار الوحيد الذي يمنح بقية الصفحة معناها. في أي CLI تقليدي تعيش الأوامر داخل العميل؛ أما في Logistivo فتعيش على الخادم.

في الترتيب التقليدي، عندما يكتسب الخادم قدرة جديدة يحتاج العميل إلى إصدار جديد ويحتاج المستخدم إلى تثبيته. وفي الفترة الفاصلة يعرف الطرفان أشياء مختلفة — وهذا أهدأ أنماط الإخفاق في التكاملات: يعمل النص البرمجي، ويكون رمز الخروج 0، والأمر ببساطة لا يصف ما يستطيع الخادم فعله.

في Logistivo يكون تعريف الأمر سجلًا واحدًا: اسمه، وما يفعله، ومعاملات JSON Schema الخاصة به، والأدوار التي يحق لها رؤيته، وما إذا كان يحتاج إلى تأكيد، وما إذا كان أثره قابلًا للتراجع. وعندما يبدأ lg يجلب هذا الكتالوج ويولّد منه نص المساعدة والخيارات (flags) والتحقق من صحة المدخلات. وفي اللحظة التي يُضاف فيها أمر على الخادم، يعرفه lg — دون أي تحديث للعميل.

يغذّي الكتالوج نفسه مساعدَ الذكاء الاصطناعي في لوحة التحكم والقناةَ التي تتصل بها مساعدات الذكاء الاصطناعي الخارجية. تُكتب القدرة مرة واحدة وتظهر في ثلاثة أماكن — وتمر الثلاثة جميعًا عبر بوابة الدور نفسها وبوابة التأكيد نفسها وسجل التدقيق نفسه. لا توجد قائمة أوامر منفصلة خاصة بـ CLI؛ ولو وُجدت لتباعدت الواجهات الثلاث بصمت في غضون ستة أشهر.

• لا انحراف بين الإصدارات — قائمة الأوامر التي يعرفها العميل هي، بحكم التصميم، القائمة الموجودة على الخادم. وسؤال «أي إصدار من lg يحتوي على هذا الأمر؟» ليس سؤالًا قائمًا أصلًا.
• أسماء الخيارات لا تُخمَّن أبدًا — خيارات الأمر هي بالضبط أسماء المعاملات في JSON Schema الخاص به. والطريقة لمعرفة ما يقبله الأمر ليست قراءة وثيقة بل قراءة الكتالوج — والكتالوج محدَّث دائمًا.
• حجم CLI لديك بحجم حسابك — الكتالوج مُرشَّح حسب الدور: الأمر الذي لا يستطيع دورك رؤيته لا يظهر في قائمتك أبدًا. يرى حساب الناقل 452 أمرًا، والشاحن 448، والمخلّص الجمركي 312، أما حساب الشريك بالإحالة (affiliate) فله مجموعته الخاصة: 55 أمرًا.
• التوثيق لا يمكن أن يتخلف عن الواقع — جدول الأوامر في هذه الصفحة يأتي من السجل نفسه. ولا توجد في أي مكان قائمة يتعين على إنسان أن يبقيها متزامنة مع الواقع.

قاعدة التسمية — كيف تنمو أسماء الأوامر

سينمو الكتالوج. ولا تُسمّى الأوامر الجديدة اعتباطًا؛ بل تُطبَّق ست قواعد. ننشرها هنا لأن هذه هي الأسماء التي سيكتبها تكاملك لسنوات، وقابليتها للتنبؤ لها قيمة لديك.

• المجال (domain) كيان بصيغة الجمع — loads و demands و invoices و export-documents. والمجالات المكوّنة من كلمتين تُكتب بصيغة kebab-case. والاستثناء الوحيد هو الاسم غير المعدود: stock لا يُجمع أبدًا، لأن «stocks» تعني شيئًا آخر.
• كل أفعال الكيان الواحد تعيش في مجال واحد — يحمل loads كل فعل يعمل على شحنة: create و list و get و update و set-status و assign-driver و list-problems و archive وغيرها. أما فتح مجال جديد لكل فعل (load-statuses و load-drivers) فسيجعل المستخدم يبحث عن الكيان نفسه في ثلاثة أماكن.
• الفعل لا يتسرّب أبدًا إلى المجال؛ المجال هو الشيء الذي يتغيّر — تعيين سائق يغيّر الشحنة لا السائق، لذا يكون الأمر lg loads assign-driver. ويُلحَق المفعول غير المباشر (-driver) بالفعل، لا بالمجال أبدًا.
• المورد الفرعي لا يحصل أبدًا على مجال خاص به — لا يمكن سرد بند الفاتورة أو عنصر المستند بمفرده؛ بل يُخاطَبان عبر مالكهما — lg invoices add-line و lg export-documents add-item. واختبار واحد يحسم الأمر: إذا لم تستطع سرد الشيء (list) أو جلبه (get) بشكل مستقل، فهو ليس مجالًا.
• التضييق خيار (flag)، لا فعل جديد — الصيغة lg fleet-documents list --days=30 صحيحة؛ ولا يوجد فعل منفصل «list-expiring»، لأن النافذة الزمنية معامل أصلًا. ولا يُستخدم الفعل المقيَّد إلا عندما لا تكون الصفوف التي يعيدها هي كيان المجال: فالأمر loads list-problems يعيد مؤشرات المشكلات، لا الشحنات.
• الزوج (domain, verb) فريد في الكتالوج بأكمله — حتى بالنسبة لأمرين لا تتداخل أدوارهما أبدًا. فلو أُعطي الزوج نفسه لأمرين، لكانت شيفرة تكاملك تنظر إلى اسم واحد بينما ينفّذ CLI أشياء مختلفة بحسب من استدعاه.

التغطية: كل ما في لوحة التحكم، عبر أمر

تربط فرق كثيرة Logistivo بوكيل الذكاء الاصطناعي الخاص بها أو بمنظومة الأتمتة لديها، والوكيل لا يكون مفيدًا إلا إذا استطاع إنجاز المهمة حتى النهاية. لذا فالقاعدة بسيطة: كل ما يستطيع موظف المكتب تغييره في لوحة التحكم، يستطيع أمرٌ تغييره أيضًا — خلف بوابة الدور نفسها، وبوابة التأكيد نفسها، وسجل التدقيق نفسه.

هذا مَقيس، لا مجرد ادعاء. فكل نقطة نهاية للكتابة خلف لوحة التحكم تُفحص مقابل سجل الأوامر، ولا تُعدّ نقطة النهاية مغطاة إلا إذا أعلنها أمرٌ نسخةً مطابقة له عبر HTTP أو استدعى الخدمة المشتركة نفسها. ومن نقاط نهاية الكتابة المشمولة بالنطاق، 100% مغطاة ولا توجد نقطة غير مُثبتة. وكل نقطة نهاية مستبعدة تحمل سببًا مكتوبًا — خطوات الهوية والدفع، ومستوى التحكم في التكامل، ونقاط النهاية الخاصة بتطبيق السائق، وقياسات العميل عن بُعد (telemetry)، والنسخ الميتة التي لا يستدعيها أحد — والنقاط التي تهم المطوّر المسؤول عن التكامل مدرجة أدناه.

والأوامر التي تأخذ ملفًا تخضع للقاعدة نفسها: إذ يأخذ 33 أمرًا في الجدول مستندًا أو صورة، وجميعها تعمل من lg وعبر HTTP وعبر MCP (انظر «الأوامر التي تأخذ ملفات»).

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

لحسابات الشريك بالإحالة (affiliate) كتالوج خاص بها: 55 أمرًا في مجالات عددها 20 — الإحالات، والعملاء المحتملون، وملاحظات CRM ومهامه، وعروض المبيعات التقديمية، والأرباح والمدفوعات، إضافة إلى أوامر الحساب والفريق التي يملكها كل دور. والأوامر الخاصة بالشريك بالإحالة وحده ليست في الجدول العام أدناه، الذي يسرد أدوار لوحة التحكم الثلاثة؛ إذ يراها حساب الشريك بالإحالة في GET /api/common/commands وفي lg commands. والشركة التي تكون شريكًا بالإحالة وفي الوقت نفسه شاحنًا أو ناقلًا أو مخلّصًا جمركيًا ترى المجموعتين كلتيهما.

ينبغي للوكيل أن يبدأ بـ lg users get (واسمه في API هو get_current_user): فهو يعيد الدور، ومستوى وصول المفتاح المستخدم، والصلاحيات الفعلية، وما إذا كانت موافقة قانونية معلّقة أو رقم هاتف غير مُتحقَّق منه يحجب عمليات الكتابة حاليًا — كي يتمكن الوكيل من توقّع الرفض بدلًا من تلقّيه.

تُقاس التغطية بتقرير يقارن سجل الأوامر بنقاط نهاية الكتابة في لوحة التحكم؛ ونقطة النهاية التي تُضاف إلى اللوحة دون أمر تظهر فيه على أنها غير مُثبتة. وإذا وجدت إجراءً في لوحة التحكم لا تستطيع الوصول إليه عبر أمر، فأبلغ الدعم بذلك.

• 1. اطلب الرابط — العمل الذي يجب أن يتم في جلسة متصفح الشخص نفسه ليس أمرًا، لكن سطح الأوامر يعرف به. إذ يعيد lg handoff-links generate (واسمه في API هو get_browser_handoff_link) رابطًا على logistivo.com للأغراض التي يسمح بها دورك: package_purchase و payment_cards و legal_documents و integration_keys و affiliate_demo_accounts و account_close. وهو مجاني، ولا يكتب شيئًا، والرابط لا يحمل أي سر — ويسجّل الشخص دخوله كالمعتاد.
• 2. سلّمه إلى الشخص — اعرض الرابط على المستخدم أو أرسله عبر قناتك الخاصة. فيُكمل الخطوة هناك: الموافقة على العقد والدفع عبر 3D Secure لشراء باقة، أو إضافة بطاقة، أو الموافقة على النصوص القانونية المعلّقة، أو إصدار مفتاح API يُعرض سرّه مرة واحدة، أو إغلاق حسابه.
• 3. اقرأ النتيجة عبر أمر — بعد إتمام الخطوة، تصبح نتيجتها مرئية للأوامر مجددًا: الباقة والرصيد، والبطاقة المحفوظة (مُقنَّعة، بآخر أربعة أرقام فقط)، والمفتاح الجديد في قائمة المفاتيح. ولا يأخذ الوكيل أبدًا رقم بطاقة أو دفعة أو موافقة في محادثة.
• المدفوعات و 3D Secure — شراء باقة أو ترقيتها وإضافة بطاقة تتطلب 3D Secure في المتصفح. أما الأوامر فتسرد الباقات والأسعار، وتقرأ الرصيد وسجله، وتسرد البطاقات المحفوظة (مُقنَّعة)، وتضبط البطاقة الافتراضية وتزيل بطاقة؛ أما الشراء نفسه فيمر عبر رابط التسليم.
• الموافقة القانونية — الموافقة على النصوص القانونية يقوم بها الشخص، في المتصفح. ويخبرك lg users get بأن هناك موافقة معلّقة؛ ولا يمكن لأي أمر أن يمنحها.
• إغلاق الحساب، وتسجيل الدخول، وكلمة المرور — إغلاق حسابك، وتسجيل الدخول، وتغيير كلمة المرور خطوات هوية تبقى في المتصفح. ويُظهر lg user-accounts preview ما سيعنيه إغلاق الحساب، دون تنفيذه.
• مفاتيح التكامل و webhooks وبيئة sandbox — إدارتها تعيد أسرارًا يجب أن تُعرض مرة واحدة، في طرفيتك، لذا فهي أوامر مدمجة في lg (lg keys و lg webhooks و lg sandbox) تعمل عبر نقاط نهاية HTTP خاصة بها، لا أوامر في الكتالوج. ولا يحمل الكتالوج إلا أمرَي المفاتيح الخاليين من الأسرار: integration-keys list و integration-keys revoke.
• محادثة المساعد في لوحة التحكم — لا يمكن لمفاتيح التكامل تشغيل محادثة مساعد الذكاء الاصطناعي داخل لوحة التحكم؛ فبدء تشغيل أو مواصلته بمفتاح يُجاب بـ 403. بل يتصل الوكيل عبر نقاط نهاية الأوامر أو lg أو قناة MCP بدلًا من ذلك — وهناك يُنفَّذ كل أمر بمستوى وصول المفتاح وتُسجَّل عمليات الكتابة فيه على أنها كتابات تكامل.
• تطبيق السائق — لا تملك حسابات السائقين كتالوج أوامر، ويحتفظ تطبيق السائق بنقاط النهاية الخاصة به. ويدير موظفو المكتب السائقين ومستنداتهم ومصروفاتهم ورحلاتهم عبر الأوامر.

التثبيت والهوية

lg نص Node برمجي في ملف واحد بلا تبعيات (Node 18+)، منشور على npm باسم @lgstv/lg. تثبّت الحزمة أمرين متطابقين، lg و logistivo — استخدم logistivo إذا كان lg معرَّفًا مسبقًا كاسم مستعار (alias) على جهازك. ولأنه ملف واحد، فإن نسخ lg.mjs إلى خادم ERP لدى أحد العملاء يعمل أيضًا. ولا تحتاج إلى العميل لبناء تكامل ERP/CRM — فالأوامر نفسها متاحة عبر HTTP.

1. التثبيت — كل ما تحتاجه هو Node 18 أو أحدث؛ ولا توجد أي تبعيات أخرى. ثبّته على مستوى النظام (globally) أو شغّله دون تثبيت عبر npx.

2. تسجيل الدخول برمز موافقة — يعرض lg login رمز موافقة قصيرًا ويفتح logistivo.com/connect في متصفحك؛ أما عبر SSH أو في CI أو مع --no-browser فيكتفي بطباعة العنوان، ويمكنك فتحه على أي جهاز، بما في ذلك هاتفك. سجّل الدخول هناك كالمعتاد، وتحقّق من أن الرمز الظاهر في الصفحة هو نفسه الظاهر في الطرفية، واختر وصولًا للقراءة فقط أو للقراءة والتنفيذ، ثم وافِق. لا يُكتب أي شيء سري في الطرفية: لا كلمة مرور ولا مفتاح ولا رمز لمرة واحدة. وبعد ذلك تبقى الجلسة مسجّلة الدخول على ذلك الحاسوب — فإغلاق الطرفية لا يسجّل خروجك، ويجدّد lg رمز الوصول (access token) بنفسه قبل انتهاء صلاحيته. ويُنهي lg logout الجلسة على الخادم أيضًا، ويمكنك إزالتها من لوحة التحكم في Settings › Integration keys › AI and CLI connections. ويبقى lg login --password (البريد الإلكتروني وكلمة المرور) متاحًا طريقًا احتياطيًا. يتطلب ذلك lg 0.11 أو أحدث.

3. للخوادم و CI: مفتاح، لا رمز موافقة — على الخادم أو في مهمة CI لا يوجد أحد ليوافق على رمز في المتصفح. أصدر مفتاحًا من لوحة التحكم (Settings › Integration keys) أو عبر lg keys create — ويمكنك اختياريًا إصداره نيابةً عن عضو فريق مخصص بصلاحيات ضيقة — ثم ضعه في LOGISTIVO_TOKEN، أو احفظه عبر lg login --api-key. وما دام المتغير مضبوطًا فلن يُقرأ ملف الإعدادات أبدًا. التفاصيل: قسم «الاتصال بمفتاح API».

4. تحقّق واستكشف الكتالوج — يسرد lg commands كل أمر يستطيع دورك رؤيته، مجمّعًا حسب المجال؛ ويطبع lg help أفعال ذلك المجال، ويطبع lg help قائمة المعاملات الكاملة لأمر واحد مع أنواعها وأيّها إلزامي. ولا يعيش أي من هذا النص داخل العميل — بل يأتي كله من الكتالوج. وتذكّر أن القائمة تعتمد على دورك: فأفعال المجال الواحد ليست نفسها لدى الناقل ولدى الشاحن (فالأمر loads set-status، على سبيل المثال، موجود في كتالوج الناقل فقط). وإذا كان فعل ما مفقودًا، فتحقق من دورك قبل أن تتحقق من التثبيت.

لا تضع المفتاح أبدًا في نظام التحكم بالإصدارات أو في سجل CI أو في نافذة محادثة. إذا سجّلت الدخول برمز موافقة أو بمفتاح تكامل، فإن lg logout يُنهي ذلك على الخادم أيضًا؛ أما في جلسة كلمة المرور (lg login --password) فإنه يحذف النسخة المحلية فقط ويصرّح بذلك بوضوح. ويخزّن سجل التدقيق وسائطك (arguments) لكنه يُخفي بالقيمة *** كل حقل يحتوي اسمه على token أو password أو IBAN أو card أو OTP، وكل معامل يعلنه الأمر سريًا.

• LOGISTIVO_TOKEN — رمز الوصول الشخصي. ما دام مضبوطًا فلن يُقرأ ملف الإعدادات أبدًا — وهذا هو المسار المفضّل في CI وعلى الخوادم.
• LOGISTIVO_BASE_URL — جذر الخادم. القيمة الافتراضية https://logistivo.com. غيّره فقط إذا كنت توجّه الطلبات إلى بيئتك الخاصة؛ والخيار --base-url يفعل الشيء نفسه لأمر واحد.
• LOGISTIVO_HOME — مجلد ملف الإعدادات وذاكرة التخزين المؤقت للكتالوج. القيمة الافتراضية ~/.logistivo. افصله إذا كنت تعمل بحسابين على جهاز واحد.
• LOGISTIVO_PROFILE — الملف الشخصي (profile) الذي يُشغَّل به. `lg profile use` هو الاختيار الدائم؛ أما هذا المتغير فلتشغيل واحد، وهو أقصر طريق للتبديل بين ملف شخصي حي وملف sandbox في CI. واسم الملف الشخصي غير المعروف لا يُتجاهل بصمت — بل يُنتج خطأ.
• NO_COLOR — عند ضبطه لا تُطبع أي ألوان ANSI (الصيغة الدائمة للخيار `--no-color`). فعّله للجسر الذي يكتب في ملف سجل أو في مخرجات CI؛ فتسلسلات الهروب الخاصة بالألوان تُفسد الأدوات التي تقرأ تلك السجلات لاحقًا.

سهولة استخدام العميل

تجعل هذه الميزات الاستخدام اليومي للعميل `lg` أسهل. ولا يغيّر أي منها عقد HTTP — تخطَّ هذا القسم إذا كنت تتكامل عبر HTTP مباشرة.

• بيئات ومفاتيح متعددة — احتفظ ببيئتي staging والإنتاج، أو بجسرَي الشاحن والناقل لديك، في ملفات شخصية منفصلة. لا تطبع قائمة الملفات الشخصية أي رمز مميز أبدًا؛ بل يعرض كل صف بصمة sha256 للرمز. ويُخزَّن كتالوج الأوامر مؤقتًا لكل ملف شخصي ومضيف ورمز، لذا لا يمكن لدورين أبدًا أن يرى أحدهما قائمة أوامر الآخر.
• المزامنة التزايدية: lg sync — يشغّل حلقة المزامنة الواردة في دليل الوصفات (cookbook) بأمر واحد: علامة مائية (watermark) لكل كيان، و updated_since مع cursor، ومخرجات JSONL، وهامش أمان مدته خمس دقائق. استخدم --full للتعبئة الأولى للبيانات السابقة (backfill). الأمر للقراءة فقط؛ ولا يوجد خيار --write. ويستنتج lg sync --list الكيانات القابلة للمزامنة لدورك من الكتالوج.
• تجربة الأخطاء والإكمال التلقائي في shell — عند 422 يسمّي العميل الحقل المرفوض باسم الخيار الذي كتبته، ويعرض error_key الثابت مع شرح الكتالوج نفسه له. وعند 409 يطبع سطر الأوامر الجاهز مع --yes؛ وعند 429 ينتظر انقضاء Retry-After. ويغطي الإكمال التلقائي في shell المجالات والأفعال والخيارات وقيم enum، ويعمل دون اتصال.
• المعاملات السرية لا تُكتب أبدًا في سطر الأوامر — تأخذ بضعة أوامر قيمة سرية — فربط تكامل المحاسبة Paraşüt، على سبيل المثال، يتطلب بيانات اعتماد العميل (client credentials) الخاصة بذلك النظام وكلمة مروره. ولا يقبل lg أبدًا مثل هذه القيمة كخيار، لأنها ستنتهي في سجل shell لديك وفي مخرجات ps: بل يطلبها دون إظهار ما تكتبه، أو يقرؤها من ---file=PATH أو من stdin (---file=-)، ويحتفظ بها في الذاكرة فقط. والأمر الذي يكون معامله الإلزامي سريًا لا يعمل إلا من lg: فإذا استُدعي من المحادثة أو عبر MCP أو داخل lg batch يُرفض بالخطأ SECRET_REQUIRES_CLI. ويسجّل سجل التدقيق القيمة دائمًا على أنها ***.

الاتصال بمفتاح API

يتصل نظام ERP أو CRM أو نص برمجي أو وكيل ذكاء اصطناعي بـ Logistivo بمفتاح تكامل صادر من لوحة التحكم أو عبر lg keys create. ويعمل المفتاح نيابةً عن عضو حقيقي في الفريق: فدور ذلك الشخص يحدد قائمة الأوامر، ومستوى وصول المفتاح يحدد مدى ثقل العمل المسموح به، وعندما يغادر ذلك الشخص الفريق يموت المفتاح معه. لا يوجد «حساب خدمة» اصطناعي ولن يوجد — فعزل المستأجرين المتعددين مرتبط بالمستخدم، والجسر الذي بلا مالك هو من النوع الذي يظل يكتب بصمت لسنوات.

1. أصدر مفتاحًا من لوحة التحكم — Settings › Integration keys › New key. امنحه اسمًا («ERP nightly sync»)، واختر النطاق ومستوى الوصول، ويمكنك اختياريًا تقصير مدة صلاحيته. يُعرض المفتاح مرة واحدة، على تلك الشاشة فقط؛ ولا يخزّنه الخادم. فإذا فقدته، يُصدر Rotate مفتاحًا جديدًا — ويصبح القديم غير صالح فورًا.

2. اتصل من الطرفية — يتحقق lg login --api-key من المفتاح، ويطبع الهوية والنطاق، وينزّل كتالوج الأوامر. ويسأل lg whoami الخادم عن المستخدم والشركة والدور والنطاق التي تعمل بها. ويلغي lg logout المفتاح على الخادم أيضًا، تمامًا كما يُنهي هناك الجلسة المفتوحة برمز موافقة (وحده lg logout في جلسة كلمة المرور لا يستطيع ذلك).

3. أو HTTP عادي — المفتاح رمز وصول يُحمل في الترويسة Authorization: Bearer ويعمل مباشرة مع نقاط نهاية الأوامر الثلاث. وعلى الخادم أو في CI ضعه في LOGISTIVO_TOKEN؛ وما دام ذلك المتغير مضبوطًا فلن يُقرأ ملف الإعدادات أبدًا.

4. أو أدِر المفاتيح من الطرفية: lg keys — lg keys هو النظير الطرفي لشاشة لوحة التحكم: نقاط النهاية نفسها، والبوابة نفسها (صلاحية إدارة الفريق، ومفتاح بمستوى manager عند استدعائه بمفتاح). وتعيد create و rotate و transfer رمزًا مميزًا جديدًا مرة واحدة: فمع --save-profile=NAME يذهب مباشرة إلى ملف شخصي محلي ولا يُطبع أبدًا؛ وإلا فيطبعه lg مرة واحدة. وفي وضع --json لا يُضمَّن الرمز إلا إذا أضفت --show-secret، واستدعاء --json الذي لا يحمل أيًّا من الخيارين يُرفض قبل إرسال الطلب، كي لا يستقر الرمز بصمت في مخرجات نص برمجي. وتطلب rotate و transfer و revoke التأكيد (--yes)؛ ويُخاطَب المفتاح باسمه الدقيق أو بمعرّف uuid الخاص به، لا بالتخمين أبدًا. وينتقل مستوى الوصول دون تغيير إلى المفتاح المُدوَّر أو المنقول.

يُفرض النطاق على سطح API بأكمله، لا على كتالوج الأوامر فحسب: فالمفتاح ذو القراءة فقط يمرّر طلبات القراءة (GET/HEAD/OPTIONS)، وكل طلب كتابة آخر يُجاب بـ 403 forbidden. وهناك استثناءان مقصودان، وكلاهما محمي ببوابة أدق: نقطة نهاية تنفيذ الأوامر (إذ يأتي القرار من علَم read_only الخاص بالأمر نفسه، لأن الأوامر التي لا تكتب تُستدعى أيضًا بـ POST)، والمفتاح الذي يلغي نفسه (lg logout، المسموح به للمفتاح ذي القراءة فقط أيضًا). والنطاق ومنح المجالات ومستوى الوصول ثلاثة محاور مستقلة ويجب اجتيازها جميعًا: فمفتاح القراءة لا يستطيع الكتابة حتى بمستوى manager، ومفتاح الكتابة بمستوى employee لا يستطيع إدارة الفريق، ومنح المجال loads:write لا يفتح أعمال الإدارة. أصدر المفتاح نيابةً عن العضو صاحب أقل الصلاحيات التي تغطي احتياجاتك: فالدور يحدد السجلات التي يمكنك رؤيتها أصلًا.

• read — كتالوج الأوامر والأوامر التي لا تكتب (list و search و preview). وأمر الكتابة يعيد 403 forbidden — قبل بوابة التأكيد؛ فالمفتاح ذو القراءة فقط لا يرى 409 أصلًا. وهو الخيار الصحيح للمزامنة الليلية والتقارير.
• write — كل الأوامر. والأوامر التي تتطلب تأكيدًا تظل تطلبه بـ 409؛ ويعمل confirm: true (أو --yes في CLI) تمامًا كما من قبل. فالنطاق لا يرخي بوابة التأكيد أبدًا.
• employee — الافتراضي لكل مفتاح جديد. العمليات اليومية: الشحنات، والطلبات، والعروض، والرحلات، والأسطول ومستندات الأسطول، والمستندات، وجهات الاتصال — أي كل أمر لا يحتاج إلى صلاحية إدارية، إضافة إلى صلاحيات الأسطول. والأمر الذي يحتاج إلى أكثر من ذلك يجيب بـ 422 مع error_key بقيمة INSUFFICIENT_KEY_LEVEL و required_key_level: manager؛ وتجيب نقطة نهاية REST المقابلة بـ 403 مع مفتاح الخطأ نفسه. وهو المستوى الصحيح للمزامنة الليلية لنظام ERP، أو لجسر أنظمة التتبع عن بُعد (telematics)، أو لنص برمجي تشغيلي.
• manager — كل ما يجوز للشخص الذي يعمل المفتاح نيابةً عنه أن يفعله، بما في ذلك الإدارة: أعضاء الفريق والأدوار، وإعدادات الشركة، ومفاتيح التكامل، والحسابات المصرفية والتحقق منها، والبطاقات المحفوظة، وعلاقات الشركة، ومدفوعات الشركاء بالإحالة. ولا يضيف مفتاح manager أبدًا حقًا لا يملكه الشخص — فمن دون صلاحية إدارة الفريق لا يستطيع إدارة الفريق مع ذلك. والمفاتيح التي كانت موجودة قبل إدخال مستويات الوصول هي مفاتيح manager، لذا تتصرف تمامًا كما كانت.
• مفتاح واحد لكل تكامل — إذا تشارك CRM و ERP مفتاحًا واحدًا، فإن قطع أحدهما يعني قطع الآخر. امنح كل جسر مفتاحه الخاص؛ فالقائمة تعرضها بأسمائها على أي حال.
• التدوير (Rotate) — يُصدر رمزًا مميزًا جديدًا ويلغي القديم فورًا؛ مع الإبقاء على مدة الصلاحية المتبقية. استخدمه عند الاشتباه في تسرّب وعلى فترات منتظمة. ويحصل التكامل على 401 إلى أن يُحدَّث بالرمز الجديد.
• الإلغاء (Revoke) — يُغلق المفتاح نهائيًا؛ ولا يمكن التراجع عن ذلك، فأصدر مفتاحًا جديدًا إذا لزم الأمر. وإذا أُزيل العضو الذي يعمل المفتاح نيابةً عنه من الفريق أو عُطّل، يسقط المفتاح تلقائيًا.
• مدة الصلاحية والحد الأقصى — مدة الصلاحية الافتراضية 180 يومًا؛ ويمكنك تقصيرها عند الإنشاء، لا تمديدها أبدًا. ويمكن للمستخدم أن يحمل 10 مفاتيح نشطة كحد أقصى. ووقت آخر استخدام ظاهر في القائمة؛ والمفتاح الذي لم يُستخدم قط يصرّح بذلك بوضوح.
• من يدير المفاتيح — الإصدار والتدوير والنقل والإلغاء متاحة للمديرين الذين يملكون صلاحية إدارة الفريق — وهي البوابة نفسها لإضافة أعضاء الفريق أو إزالتهم — وعند تنفيذها بمفتاح تكامل، يجب أن يكون ذلك المفتاح بمستوى manager. ويمكن للمدير إصدار مفتاح نيابةً عن عضو آخر؛ ويُوصى للجسر بعضو مخصص بصلاحيات ضيقة.

الدقائق العشر الأولى: من لوحة التحكم إلى استدعائك الأول

أغلى دقائق التكامل هي الدقائق العشر الأولى. وتعرض الخطوات الأربع أدناه هذا المسار بالترتيب؛ والترتيب نفسه موجود في لوحة التحكم على شكل معالج (Settings › Integration › Setup wizard)، ويستدعي المعالج بالضبط نقاط النهاية الموصوفة هنا. والمطوّر الذي لا يملك وصولًا إلى المعالج يصل إلى المكان نفسه بقراءة هذا القسم.

لا تنتهي أيٌّ من الخطوات الأربع بعبارة «لقد أرسلته». فسجل الطلبات هو ما يجيب عمّا إذا كان المفتاح يعمل فعلًا؛ وسجل التسليمات هو ما يجيب عمّا إذا كان webhook يصل فعلًا. وكلاهما متاح في لوحة التحكم وفي lg. والإعداد الذي لا يُقاس أبدًا هو إعداد يُعتقد فحسب أنه يعمل.

• 1. قرّر ما ستفعله — اضبط النطاق أولًا — لا مجال لأن تقرر لاحقًا ما يجوز للمفتاح رؤيته: فأنت تختار النطاق عند إصداره. وهناك محوران. النطاق العام (read / write) يجيب فقط عن سؤال «هل يجوز له الكتابة». أما النطاق الدقيق (منح المجالات: loads:read و invoices:write) فيحدد المجالات التي يجوز له لمسها، وفي اللحظة التي يُضبط فيها يصبح المفتاح مغلقًا عند الإخفاق (fail-closed) — فكل مجال لم تختره، وكل نقطة نهاية لا تقابل أي مجال، يعيد 403. وقائمة المجالات في لوحة التحكم ليست قائمة مكتوبة يدويًا؛ بل تُستمد من كتالوج الأوامر الحي لدورك وتُظهر عدد الأوامر ونقاط نهاية REST التي يفتحها كل مجال. ونقاط نهاية كتالوج الأوامر و«من أنا» (current) و«تسجيل الخروج» مستثناة دائمًا من النطاق: إذ يجب أن يتمكن المفتاح دائمًا من وصف نفسه وإغلاق نفسه. والمحور الثالث هو مستوى الوصول: employee (الافتراضي) ينفّذ العمليات اليومية، و manager يقوم أيضًا بأعمال الفريق والإعدادات والمفاتيح والمال. اختر employee ما لم يكن الجسر يقوم بأعمال إدارية.
• 2. أصدر المفتاح — يُعرض الرمز المميز مرة واحدة — Settings › Integration › New key. امنحه اسمًا («ERP nightly sync»)، واختر المستخدم الذي يعمل نيابةً عنه ومستوى الوصول، وقصّر مدة الصلاحية إن أردت. ولا يُعاد الرمز المميز الخام إلا في تلك الاستجابة؛ ولا يخزّنه الخادم، ولا يوجد «عرض مرة أخرى» في لوحة التحكم. فإذا فقدته، فدوّره للحصول على رمز جديد ويموت القديم فورًا. لا تضع الرمز أبدًا في نظام التحكم بالإصدارات أو في سجل CI أو في نافذة محادثة؛ بل ضعه في مخزن الأسرار الخاص بالنظام المستهدف.
• 3. أجرِ الاستدعاء الأول — وتأكد من أنه وصل فعلًا — يكفي طلبان. الأول يُثبت هويتك (وهو مستثنى من النطاق ويعمل مع كل مفتاح): هل النطاق كما توقعت، وهل الحالة نشطة، وهل يقترب expires_at. والثاني يقرأ بيانات حقيقية من المجال الذي اخترته. فإذا نجح، فالهوية والنطاق وبوابة البريد الإلكتروني ومسار الشبكة كلها صحيحة. وإذا لم ينجح، فلا تخمّن: فسجل الطلبات الخاص بالمفتاح يُظهر، صفًا صفًا، أي نقطة نهاية رُفضت وبأي رمز وبأي مفتاح خطأ ثابت (INSUFFICIENT_SCOPE و IP_NOT_ALLOWED و KEY_ACTOR_BLOCKED …). وفي لوحة التحكم يكون هذا السجل نافذة «Recent requests»؛ وفي الطرفية يكون lg logs. ويراقب المعالج هذا السجل تحديدًا ويرفض تحويل الخطوة إلى اللون الأخضر حتى يرى استدعاءً ناجحًا حقيقيًا.
• 4. اضبط webhook — وتحقّق من التوقيع قبل أي شيء آخر — انتظار الأحداث أرخص من السؤال كل دقيقة. سجّل عنوان https، واختر الأحداث التي تهمك، واربط الاشتراك بمفتاحك: فإذا أُلغي المفتاح، يتوقف التسليم أيضًا. ولا يُعرض السرّ إلا مرة واحدة، عند الإنشاء. ويجب على نقطة النهاية المستقبِلة لديك أن تتحقق من التوقيع أولًا: فالسلسلة الموقَّعة هي "{t}.{raw body}" والخوارزمية HMAC-SHA256؛ والطابع الزمني موجود داخل التوقيع، لذا أسقط أي طلب أقدم من 300 ثانية حتى لو كان التوقيع صالحًا. قارن في زمن ثابت ولا تُعِد تسلسل الجسم أبدًا — ففي اللحظة التي تحلّل فيها JSON ثم تطبعه مجددًا يتوقف التوقيع عن المطابقة. ومن لوحة التحكم، يُطلق «Send test» طلب ping حقيقيًا موقَّعًا ويمكنك متابعة التسليم محاولةً بمحاولة.

بيئة الاختبار (sandbox): تدرّب على الكتابة دون المساس ببيئة الإنتاج

يخبرك الفحص المسبق (dry_run) بما سيفعله الأمر؛ لكن ما إذا كان عدم التكرار يعيد النتيجة فعلًا، وما إذا كان webhook يُسلَّم فعلًا، وكيف تبدو فروع الأخطاء، ومن أين يُخصم الرصيد، كل ذلك لا يمكن رؤيته إلا في عملية كتابة حقيقية. ولهذا وُجدت بيئة sandbox: مستأجر منفصل يحاكي شركتك — بالشيفرة نفسها، وكتالوج الأوامر نفسه — ولا يمس أبدًا دفترك الحي.

بيئة sandbox ليست علَمًا في الطلب، بل مستأجر (tenant). شركة Logistivo منفصلة تُفتح لشركتك: بمستخدمها الخاص، وباقتها الخاصة، ودفتر رصيدها الخاص، واشتراكات webhook الخاصة بها. وتُستنتج البيئة من شركة المفتاح ولا يمكن للمستدعي تمريرها، لذا حتى لو اخترت الملف الشخصي الخاطئ يتوقف الطلب في جهة الخادم بالخطأ 403 ENVIRONMENT_MISMATCH. فعبارة «ظننت أنني أكتب في sandbox فكتبت في بيئة الإنتاج» مستحيلة بنيويًا.

السطح متطابق — وهذا مَقيس: فالكتالوج الذي يحصل عليه مفتاح sandbox هو نفسه الذي يحصل عليه مفتاحك الحي (في مفتاح الشاحن، 448 أمرًا في الجانبين). والجسر الذي يعمل في sandbox يعمل في بيئة الإنتاج؛ ولا شيء مما تتعلمه يحتاج إلى أن يُتعلَّم مرتين.

لا تُفتح بيئة sandbox فارغة: بل تحتوي على بيانات أولية مُولَّدة (غير منسوخة) — جهات اتصال، وشحنات في الاتجاهين، وطلبات. والأسماء مختلَقة بشكل صريح، وعناوين البريد الإلكتروني تقع في النطاق @sandbox.invalid؛ ولا يُقرأ أبدًا صف أي مستأجر حقيقي ولا يُستنسخ ولا يُستخدم كقالب.

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

• 1. افتح بيئة sandbox — بيئة sandbox واحدة لكل شركة. وتتطلب نقطة النهاية صلاحية إدارة الفريق (team.manage)، لذا يتولى ذلك أحد المسؤولين في شركتك. وإذا كانت موجودة مسبقًا، تجيب نقطة النهاية نفسها عبر GET بحالتها: معرّف الشركة، والرصيد المتبقي، وعدد المفاتيح النشطة، والاشتراكات، وسجل الأجيال، والحدود القصوى.
• 2. أصدر مفتاح sandbox واحتفظ به كملف شخصي ثانٍ — يُصدر المفتاح نيابةً عن مستخدم الجسر الخاص ببيئة sandbox ويعود موسومًا بـ environment: sandbox؛ ولا يظهر الرمز المميز الخام إلا في تلك الاستجابة الواحدة. وفي جانب lg لا تستبدل مفتاحك الحي — بل احتفظ بالاثنين كملفين شخصيين منفصلين؛ فـ --sandbox و --live محددان لتشغيل واحد.
• 3. اكتب فعلًا — لا --dry-run هنا؛ فالكتابة هي الغاية كلها. أرسل مفتاح عدم التكرار نفسه مرتين وراقب الاستجابة الثانية وهي تعود بـ status: replayed — وهذه هي النتيجة المَقيسة في sandbox. واستدعِ عن قصد أمرًا خاضعًا للبوابة دون تأكيد واقرأ جسم 409؛ وجرّب أمرًا خارج نطاقك واقرأ الرفض. ولا يترك أيٌّ من ذلك أثرًا في دفترك الحي: فرصيدك الحي لا يتغيّر طوال التشغيل نفسه.
• 4. اقرأ قائمة التحقق قبل الانتقال إلى البيئة الحية — تجيب نقطة نهاية go-live بناءً على ما فعلته فعليًا في sandbox: هل كتبت، وهل رأيت فروع الأخطاء، وهل سُلِّم webhook، وهل نقلت المستقبِل من عنوان التجربة، وهل وضعت تاريخ انتهاء للمفتاح. ويعود كل بند بإحدى القيم pass / todo / unknown. وتحمل الاستجابة نفسها أيضًا مقترحًا للنطاق مستمدًا من الأوامر التي استدعيتها فعليًا — استخدمه لإصدار مفتاحك الحي بنطاق لا يتجاوز حاجتك.
• الرصيد والفوترة — لبيئة sandbox دفتر رصيد خاص بها، ولا يتحرك رصيدك الحي. وهذه بنية، لا مجرد فحص: فالرصيد يُحتسب لكل شركة، وبيئة sandbox شركة منفصلة. وهي تُفتح على الفئة المجانية، وليس لها وسيلة دفع، وتقع خارج نافذة التحصيل الشهري — ولا يمكنها الوصول إلى فاتورة بأي طريق.
• السوق — الطلب الذي تفتحه في sandbox لا يظهر على شاشات الناقلين الحقيقيين ولا يصل إلى بريدهم الإلكتروني أو إشعارات push لديهم؛ ولا ترى أنت أيضًا الطلبات الحقيقية. والفصل متماثل ومفروض في استعلامين منفصلين: فمَن يرى الطلب ومَن يُرسل إليه سؤالان مختلفان.
• Webhooks — تحمل الاشتراكات وسم البيئة أيضًا. فحدث sandbox لا يُسلَّم أبدًا إلى اشتراك حي، والحدث الحي لا يصل أبدًا إلى اشتراك sandbox؛ وللاشتراك الذي انحرف وسمه لا يُفتح أي تسليم على الإطلاق. ولأن الحد الأقصى للاشتراكات يُحتسب لكل شركة، فإن اشتراكات التجربة لا تستهلك من حصتك الحية.
• البيانات الأولية — السجلات النموذجية داخل sandbox مُولَّدة، ولا تُنسخ أبدًا من مستأجرين حقيقيين. والتعبئة الأولية عديمة التكرار (idempotent): فالاستدعاء الثاني لا يضع دفعة ثانية من البيانات فوق سجلاتك.
• الكتالوج نفسه — دورك هو دورك في sandbox أيضًا، وقائمة الأوامر متطابقة — وهذا مَقيس: 448 أمرًا في الجانبين. فبيئة sandbox ليست عرضًا تجريبيًا مقلّصًا؛ بل هي توأم لشركتك.
• حدّ اليوم: لا يمكن إدارة اشتراكات webhook بمفتاح sandbox — تتطلب نقاط نهاية الاشتراكات صلاحية إدارة الفريق (team.manage)، ومستخدم الجسر في sandbox لا يحمل أي دور في الفريق، لذا يجيب `lg --sandbox webhooks …` اليوم بـ 403. وسطح الأوامر كله يعمل — والقيد على سجل الاشتراكات فقط. وإذا أردت التدرب على webhooks في sandbox، فاطلب ذلك من الدعم؛ فهذه ثغرة مَقيسة ومسجّلة كمسألة مفتوحة.
• GET /api/common/integration-sandbox — الحالة: هل هي موجودة، وأي شركة، والرصيد المتبقي، وعدد المفاتيح النشطة والاشتراكات، وسجل الأجيال، والحدود القصوى، ودليل محفّزات يبيّن أي أمر يُطلق أي حدث.
• POST /api/common/integration-sandbox — يفتح بيئة sandbox (واحدة لكل شركة، وعديم التكرار idempotent). ويتطلب الصلاحية team.manage.
• POST /api/common/integration-sandbox/keys — 201 + المفتاح والرمز المميز الخام (هنا فقط، ومرة واحدة فقط). ويُستنتج الوسم environment: sandbox من الشركة؛ ولا يمكن للمستدعي تمريره.
• GET /api/common/integration-sandbox/go-live — قائمة التحقق قبل الانتقال إلى البيئة الحية (go-live) ومقترح للنطاق — محسوبان من حركة طلباتك الحقيقية في sandbox.
• POST /api/common/integration-sandbox/renew — يفتح جيلًا جديدًا من sandbox ويُحيل الجيل السابق إلى التقاعد.

نموذج الأوامر

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

lg loads list --status=in_transport --limit=20 --json

أسماء الخيارات هي أسماء المعاملات في المخطط، ويقبل lg كلا الهجاءين: --load_code و --load-code يصلان إلى الحقل نفسه (ويطبع lg help صيغة kebab-case). لذا فرؤية الخيار تخبرك بحقل JSON الذي ينتهي إليه، والانتقال من CLI إلى HTTP لا يحتاج إلى أي ترجمة للأسماء. والمعامل المنطقي (boolean) المكتوب بلا قيمة يساوي true (--only_open)؛ وعكسه --no-only_open. اكتب الوسيط الذي تبدأ قيمته بشَرطة على الصورة --flag=value ، وإلا فإن خيارًا منسيًّا سيبتلع الخيار التالي بصمت على أنه قيمته. وفي الأمر الذي يأخذ ملفًا، ضع @ قبل المسار المحلي (--attachment_uuid=@./cmr.pdf) — انظر «الأوامر التي تأخذ ملفات».

• lg — برنامج العميل.
• loads — المجال — الكيان الذي تعمل عليه، بصيغة الجمع.
• list — الفعل — ما تفعله بذلك الكيان، مأخوذ من مفردات مغلقة لا تتوسع إلا بقرار مدروس: أفعال بسيطة (list و get و create و update و delete و search و preview و generate و extract …) وأفعال مركّبة تسمّي ما يُلحَق أو يُغيَّر (add-document و set-status و assign-driver). ويسرد الأمر lg help أفعال مجال ما.
• --status=in_transport — معامل — اسمه هو بالضبط اسم المعامل في JSON Schema ويجب أن تطابق قيمته نوع المخطط. والقيمة غير الصالحة في حقل من نوع enum لا تصل إلى الخادم أبدًا.
• --limit=20 — عدد الصفوف في أوامر القوائم. يُذكر الحد الأقصى في وصف معاملات كل أمر — وعادةً ما يكون 20 في استدعاء القائمة العادي وحتى 100 في وضع المزامنة (مع cursor أو updated_since).
• --json — مخرجات JSON خام.
• --json — يطبع JSON خامًا. وهذا هو الشكل الصحيح الوحيد للنصوص البرمجية: فالجدول المحاذى الافتراضي مخصص للبشر، ويختار أعمدته من البيانات، وقد يتغيّر تخطيطه دون إشعار. لا تكتب أبدًا نصًا برمجيًا يحلّل مخرجات الجدول.
• --yes, -y — يجتاز بوابة التأكيد (confirm: true عبر HTTP). استخدمه فقط في نص برمجي يعرف ما هو مقدم عليه؛ ففي الأمر غير القابل للتراجع يعني هذا الخيار اختصارًا: «لا تراجع».
• --idempotency-key= — يجعل إعادة محاولة أمر الكتابة آمنة. فالاستدعاء الثاني بالمفتاح نفسه لا يعيد تشغيل الأمر؛ بل يعيد النتيجة الأولى. وإذا بنيت حلقة لإعادة المحاولة، فولّد المفتاح بنفسك وأرسل المفتاح نفسه في كل محاولة.
• --dry-run — يشغّل فحصًا مسبقًا بدلًا من الأمر: يجري التحقق من الصحة والبوابات وحساب الرصيد، ولا يُكتب شيء (انظر قسم الفحص المسبق). صالح مع كل أمر ومع lg batch.
• --refresh — يفرض تحديث الكتالوج. يخزّن lg الكتالوج مؤقتًا لمدة ساعة؛ فإذا كنت تعلم أن أمرًا أُضيف للتو على الخادم، فاستخدم هذا الخيار بدلًا من الانتظار.
• --help, -h — يطبع وصف الأمر في الكتالوج، وكل معامل، ونوعه، وقيم enum الخاصة به، وما إذا كان إلزاميًا. لا يوجد ملف مساعدة داخل العميل.
• --profile=, --sandbox, --live — الملف الشخصي الذي يُشغَّل به هذا الاستدعاء الواحد. يختار --sandbox و --live الملف الشخصي الذي يحمل مفتاح sandbox أو مفتاحًا حيًا؛ وتُستنتج البيئة من المفتاح على الخادم، لذا يتوقف عدم التطابق بالخطأ 403 ENVIRONMENT_MISMATCH بدلًا من الكتابة في المكان الخاطئ.
• --base-url, --timeout, --verbose, --no-color, --version — على الترتيب: توجيه أمر واحد إلى خادم آخر، ومهلة بالثواني، وتفاصيل الطلب/الاستجابة، وتعطيل ألوان ANSI، وإصدار العميل.

أمثلة حقيقية

كل أمر أدناه موجود في الكتالوج اليوم؛ ولا يوجد هنا اسم أو معامل مختلَق. المخرجات مختصرة. وتعرض المخرجات مستوى `data.result`؛ أما عبر HTTP فيصل الكائن نفسه داخل الغلاف `{success, data:{…}}` (انظر «واجهة API للأوامر عبر HTTP»).

• الشحنات الموجودة على الطريق حاليًا — lg loads list --status=in_transport --limit=20
• شحنة واحدة بالكامل، بصيغة JSON خام — lg loads get --load_code=FSK2158 --json
• مؤشرات اتساق المستندات المفتوحة — lg loads list-problems --only_open=true --limit=10
• حدّد الدولة — lg countries search --query=Germany --json
• رشّح باستخدام المعرّف الذي حصلت عليه — lg loads list --receiving_country_id=57 --date_from=2026-09-01 --limit=20
• اعثر على رمز HS من اسم منتج — lg tariffs search --query="aluminium profile"
• انقل شحنة إلى المرحلة التالية (لدور الناقل فقط) — lg loads set-status --load_code=FSK2158 --status=transit --date=2026-08-21 --yes
• المسودة — lg export-documents create --doc_type=proforma-invoice --currency_code=EUR --json
• ولّده (خاضع للبوابة) — lg export-documents generate --document_id=8412 --yes

دون العميل: واجهة API للأوامر عبر HTTP

lg وسيلة للراحة، لا البوابة الوحيدة. فالكتالوج والتنفيذ كلاهما يمران عبر ثلاث نقاط نهاية HTTP (وللملفات نقطة رابعة هي نقطة نهاية الرفع — انظر «الأوامر التي تأخذ ملفات»)؛ ويتصل تكامل ERP أو CRM هنا مباشرة. والهوية رمز وصول شخصي يُحمل في Authorization: Bearer. وكل استجابة، دون استثناء، تعود في الغلاف نفسه: `{ "success": bool, "data": { … }, "code": "…", "message": { … } }`. ويعيش العقد كله داخل `data` — `contract_version` و `command` و `status`، و `result` بوصفه مخرجات الأمر؛ وعند الإخفاق `error_code` و `error_key` و `error`. وتعرض أمثلة الاستجابات في هذه الصفحة الكائن `data` بدلًا من الغلاف توفيرًا للمساحة؛ فلا تنسَ فك الغلاف واستخراج `data` في شيفرتك. كما يطبع `lg --json` الغلاف كاملًا، ولهذا تبدأ مسارات jq بـ `.data.result…`. والاستثناء الوحيد هو `/api/public/status`: فنقطة النهاية هذه بلا غلاف كي تتمكن أدوات المراقبة من إطلاق التنبيه دون تحليلها.

طلب التأكيد عبر 200 + ok:false محظور ولن يحدث أبدًا. والسبب بسيط: فالعملاء يعاملون 200 على أنها نجاح، لذا فإن طلب تأكيد يُعاد بالرمز 200 سيقتل التدفق بصمت ولن يلاحظ أحد. التأكيد دائمًا 409.

• GET /api/common/commands — الكتالوج الكامل الذي يستطيع دورك رؤيته: contract_version؛ ولكل أمر name و domain و verb و description و JSON Schema و read_only و confirmation_needed و irreversible و credit_cost و since و deprecated_at و replaced_by و aliases، وحقول الوصول key_level و permission و file_params و secret_parameters و cli_only؛ وعلى المستوى الأعلى قاموس error_keys، و rate_limits، و idempotency_ttl_hours، وأدوار الكتالوج الخاصة بك، وعقد المرفقات attachments (الرفع)، ومستوى وصول المفتاح الذي تستدعي به. يرسل ETag؛ ويجيب If-None-Match بالرمز 304. ويطابق ?domain= أيضًا مجالًا قديمًا (اسمًا مستعارًا alias). ابنِ عميلك من هذا؛ ولا تكتب قائمة أوامر ثابتة في الشيفرة.
• GET /api/common/commands/{name} — أمر واحد بالكامل. name هو اسم الأمر المُجمَّد من الكتالوج (list_loads)، لا هوية CLI. ويجيب الأمر المُهمَل بالترويسة X-Deprecated.
• POST /api/common/commands/{name} — التنفيذ. الجسم: { args, confirm?, idempotency_key? }. حالة HTTP في الاستجابة هي النتيجة نفسها — فكل ما عدا 200 معلومة، لا ضجيج. وتحمل الأخطاء error_code (على مستوى النقل)، وفي حالات الرفض المتعلقة بمنطق الأعمال error_key.

الأوامر التي تأخذ ملفات

يأخذ 33 أمرًا في الجدول مستندًا أو صورة: إرفاق CMR بشحنة، وقراءة رموز HS من فاتورة، وإنشاء مركبة من مستند تسجيلها، وتقدير منصّة نقّالة (pallet) من الصور، ورفع مستند للشركة، ومطابقة فاتورة مع قائمة التعبئة (packing list). في المتصفح تُسقط الملف في نموذج؛ أما في أي مكان آخر فيتطلب الأمر خطوتين — ارفع الملف، ثم مرّر معرّفه إلى الأمر.

يأخذ المعامل ملفًا عندما ينتهي اسمه بـ attachment_uuid أو attachment_uuids — مثل photos[].attachment_uuid داخل قائمة، و front_attachment_uuid في الشيك. ولا يتعين عليك تذكّر ذلك: فكل صف في الكتالوج يحمل file_params بالمسارات الدقيقة، ويَسِم المخطط تلك الحقول (format: uuid، x-logistivo-file: true)، وتحمل استجابة الكتالوج كتلة attachments تتضمن عنوان الرفع، والأنواع المقبولة، وحدود الحجم، ومدة الصلاحية. ويُظهرها lg help أيضًا.

الرفع عملية كتابة، لذا لا يستطيع المفتاح ذو نطاق القراءة الرفع؛ أما أي مفتاح بنطاق الكتابة فيستطيع، بأي من مستويَي الوصول. والملفات المرفوعة تخص المستخدم، لا المفتاح: فمفتاحان للمستخدم نفسه يريان الملفات المرفوعة نفسها، ولا يستطيع أحد استخدام ملفات غيره. والمعرّف غير المعروف أو المنتهي الصلاحية أو الذي لا يخصك يُعامل ببساطة على أنه غير موجود، ولا يُكشف السبب.

مرفقات محادثة لوحة التحكم والملفات المرفوعة للأوامر مساحتان منفصلتان: فالملف المرفق في محادثة المساعد لا يمكن تمريره إلى أمر بمعرّفه، والملف المرفوع لأمر لا يظهر أبدًا في سلسلة محادثة.

الرفع ليس أمرًا وليس له أثر على الأعمال بمفرده: فلا يحدث شيء لبياناتك إلى أن يستخدم أمرٌ المعرّف. ولهذا السبب أيضًا لا يطلب الرفع تأكيدًا أبدًا — فالأمر الذي يستهلك الملف هو الذي يحمل البوابة.

• 1. lg: ضع @ قبل المسار المحلي — يرفع lg الملف أولًا، ثم يشغّل الأمر بالمعرّف المُعاد؛ والقيمة التي لا تبدأ بـ @ هي معرّف ملف رفعته سابقًا. وتأخذ القوائم مسارات مفصولة بفواصل أو خيارًا مكررًا، وتأخذ الحقول المتداخلة JSON، و --file اختصار عندما يكون للأمر حقل ملف واحد بالضبط في المستوى الأعلى. ويتحقق lg من كل ملف محليًا (الوجود، والحجم، والنوع) قبل إرسال أي شيء، ويرفع lg batch كل ملف مميز مرة واحدة قبل تشغيل الدفعة.
• 2. HTTP: ارفع، ثم مرّر attachment_uuid — أرسل الملف بصيغة multipart/form-data في حقل اسمه file. والرفع الجديد يجيب بـ 201؛ أما الملف نفسه إذا رفعه المستخدم نفسه مرة أخرى فيجيب بـ 200 مع الحالة replayed والمعرّف نفسه، ولا يُكتب شيء. وكما في كل مكان في هذه الصفحة، يعرض المثال الكائن data داخل الغلاف.
• 3. MCP: الأداة upload_attachment — لا يستطيع عميل MCP إرسال multipart، لذا توفر القناة أداة إضافية واحدة ليست في الكتالوج: تأخذ upload_attachment اسم الملف والمحتوى بترميز base64 وتعيد attachment_uuid نفسه. وهي تستدعي الخدمة نفسها التي يستدعيها الرفع عبر HTTP، وبالقواعد نفسها.
• النوع يُستمد من المحتوى — يُتجاهل اسم الملف والنوع المُعلَن؛ فالامتداد المخزَّن هو الامتداد المكتشف. المقبول للرفع: jpg, jpeg, png, webp, heic, heif, pdf, xlsx, xls, csv, txt, doc, docx, xml, zip. ثم يطبّق كل أمر قائمته الخاصة الأضيق قبل تشغيل أي شيء، ويجيب بـ UNSUPPORTED_FILE_TYPE مع الأنواع المقبولة، أو بـ FILE_TOO_LARGE.
• الحجم — الصور حتى 10 MB، والملفات الأخرى حتى 15 MB.
• مدة الصلاحية — يمكن استخدام الملف المرفوع لمدة 24 ساعة. وبعد ذلك لا يُعثر عليه (ATTACHMENT_NOT_FOUND) — لكنه لا يُحذف. ارفعه مرة أخرى إذا فشل أمر لهذا السبب.
• الملف نفسه، المعرّف نفسه — رفع الملف نفسه مرة أخرى (بالاسم والحجم والمحتوى نفسها) يعيد المعرّف الموجود بدلًا من كتابة معرّف جديد، ما دامت قد بقيت له ساعة على الأقل، ولا يستهلك من حدك اليومي.
• الحدود اليومية — 300 عملية رفع لكل مستخدم يوميًا (TOO_MANY_FILES) و 2 GB لكل شركة يوميًا (DAILY_LIMIT_REACHED)؛ ويجيب كلاهما بـ 429 مع retry_after.
• POST /api/common/commands:upload — رفع بصيغة multipart في الحقل file. و 201 للرفع الجديد، و 200 مع الحالة replayed للملف نفسه. ويعيد data.attachment: attachment_uuid و filename و mime_type و size_bytes و sha256 و extraction_status و expires_at و reused.

بوابة التأكيد والأوامر غير القابلة للتراجع

يحمل كل أمر في الكتالوج علَمين: confirmation_needed (هل يتطلب موافقة صريحة قبل التشغيل) و irreversible (هل يمكن التراجع عن أثره). وهما سؤالان منفصلان، ويُفرض كلاهما على الخادم بدلًا من تركهما لحسن تصرّف العميل.

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

تُقرأ البوابة من الأمر الفعلي. فعندما يغلّف أمرٌ أمرًا آخر — كما يفعل المنفّذ العام في المحادثة — تأتي البوابة من أعلام الأمر الذي سيُنفَّذ فعلًا، لا من الغلاف. ومع علَم ثابت كان لا بد من وقوع أحد إخفاقين: إما أن يعمل أمر الفاتورة دون تأكيد، أو أن يُظهر كل بحث عن دولة بطاقة تأكيد.

read_only وعدم الخضوع للبوابة ليسا الشيء نفسه. فهناك ثلاث حالات متمايزة: invoices preview لا يخضع للبوابة ولا يكتب شيئًا؛ و loads create يخضع للبوابة ويكتب؛ و invoices create لا يخضع للبوابة لكنه يكتب — إذ تنشأ مسودة. واختبار واحد يحسم الأمر: عندما يعود الأمر، هل تغيّر صف في قاعدة البيانات؟

بعض الإجراءات ليست خلف هذه البوابة لأنها ليست أوامر أصلًا: شراء باقة، وإضافة بطاقة عبر 3D Secure، والموافقة على النصوص القانونية، وإغلاق الحساب، كلها تتم في متصفح الشخص نفسه. ولهذه الإجراءات يعيد lg handoff-links generate رابطًا على logistivo.com — مجانيًا، لا يكتب شيئًا، ولا يحمل أي سر — ويُكمل الشخص الخطوة هناك. ولا يوجد خيار، مهما كان ضبطه، يحوّل دفعة أو موافقة إلى استدعاء API.

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

• 1. استدعِه — استدعِ الأمر الخاضع للبوابة دون confirm. لا يتغيّر شيء.
• 2. اقرأ الملخص — تحصل على 409؛ و confirmation.summary في الجسم جملة مكتوبة للبشر («About to issue an invoice: X Ltd, 1,200.00 TRY»)، لا تفريغ للوسائط الخام. كما تحمل الأوامر المالية معاينة منظمة: بنود، ومجاميع، وتحذيرات.
• 3. أكّد — كرّر الاستدعاء نفسه مع confirm: true (أو --yes في CLI). وتُوسَم الأوامر غير القابلة للتراجع بحيث لا تُنفَّذ أكثر من مرة واحدة.

الفحص المسبق: اعرف ما سيفعله أمر الكتابة دون تشغيله

أغلى خطوة في ربط جسر ERP هي اكتشاف ما إذا كان جسم طلبك صحيحًا عبر تشغيل الأمر فعليًا: مسودة فاتورة في الدفتر الحي، ورصيد مستهلَك، وتنظيف يدوي. و dry_run يُنهي ذلك — تضيف حقلًا واحدًا إلى الطلب، فلا يُنفَّذ الأمر، وتقرأ ما كان سيحدث.

يضم السجل اليوم 519 أمرًا؛ منها 233 تقرأ فقط ولا تكتب شيئًا. ومن أوامر الكتابة المتبقية البالغ عددها 286، يخضع 251 للبوابة: فعند استدعائها دون confirm تجيب أصلًا بالرمز 409 وتصف ما كانت ستفعله. أما الثغرة فكانت في الأوامر الأخرى البالغ عددها 35 — مسودات الفواتير، ومسودات مستندات التصدير، والبنود: أي بالضبط السلسلة التي يربطها الجسر أولًا. ففي هذه الأوامر كان الاستدعاء يعني التنفيذ.

وكانت هناك ثغرة ثانية حتى في الأوامر الخاضعة للبوابة: فالتحقق من المخطط يجري بعدَ البوابة. لذا كان الاستدعاء الذي ينقصه وسيط يحصل أولًا على بطاقة التأكيد، فيؤكدها، ثم يسمع بعد ذلك فقط «هذا الحقل مفقود». أما الفحص المسبق فيجيب عن الأمرين في رحلة ذهاب وإياب واحدة.

وأكثر أخطاء الجسور شيوعًا — وآخرها اكتشافًا — هو التالي: ترسل حقلًا غير موجود في المخطط (customer_id حيث يُتوقع recipient_contact_id)، فيُسقطه الخادم بصمت، ويعيد الأمر 200، ويستقر السجل في المكان الخاطئ. وتسرد استجابة الفحص المسبق هذه الحقول بأسمائها تحت arguments.ignored؛ وهذا ما لن تفعله أي رسالة خطأ أبدًا.

الفحص المسبق لا يكتب شيئًا، وهذا أمر بنيوي قبل أن يكون نتيجة قياس: فمسار الفحص المسبق لا يدخل أبدًا إلى معالج الأمر، لذا يصح ذلك على كل أمر، بما في ذلك الأوامر المضافة لاحقًا. وقد قيس ذلك أيضًا عند إطلاقه: إذ التُقطت كل عبارة SQL صدرت أثناء إجراء الفحص المسبق لكل أوامر الكتابة في الكتالوج آنذاك (مجموعتا وسائط، ودوران، و 178 فحصًا مسبقًا). فلم تصدر ولا عبارة INSERT/UPDATE/DELETE واحدة، ولا مهمة واحدة في الطابور، ولا بريد إلكتروني واحد؛ وبقيت أعداد الصفوف في 31 جدولًا والرصيد المتاح دون تغيير.

رمز الخروج هو نفسه الذي سيُنتجه الاستدعاء الحقيقي — 0 إذا كان سيُنفَّذ، و 4 لبوابة التأكيد، و 2 لتعارض عدم التكرار، و 1 لأي شيء آخر — لذا فإن "lg … --dry-run || exit" بوابة ذات معنى في خطوة CI.

• 1. استدعِه مع dry_run — أضف "dry_run": true إلى جسم الطلب. يجري التحقق من الصحة، وبوابة الدور والنطاق (scope)، وتحديد الهدف، وحساب الرصيد؛ أما الأمر نفسه فلا يُنفَّذ.
• 2. اقرأ would_execute — هذا هو العلَم الوحيد الذي يُبنى عليه التفرّع. فعندما تكون قيمته false، يسمّي would_stop.at الموضع الذي سيتوقف عنده الاستدعاء الحقيقي: idempotency أو target_precheck أو confirmation_gate أو arguments.
• 3. صحّح جسم الطلب — يسمّي arguments.ignored الحقول التي ستُسقط بصمت، و missing_required الحقول الإلزامية التي أغفلتها، و would_charge عدد وحدات الرصيد التي ستُخصم وما إذا كان الرصيد المتاح يغطيها.
• 4. أزِل dry_run — كرّر حتى تصبح قيمة would_execute هي true، ثم أزِل العلَم وأجرِ الاستدعاء الحقيقي. فمفتاح عدم التكرار الذي أرسلته أثناء الفحص المسبق لم يُستهلك، لذا يعمل الاستدعاء الحقيقي بشكل طبيعي.
• HTTP دائمًا 200 — عبارة «سيفشل الأمر» لا تصل أبدًا كاستجابة 4xx — فالفحص المسبق نفسه نجح والتوقّع موجود في الجسم. والاستثناء هو الرفض على مستوى النقل، وهناك يتصرف تمامًا مثل الاستدعاء الحقيقي: 404 لأمر غير معروف، و 403 للدور/النطاق، و 429 لحد المعدل.
• مفتاح بنطاق القراءة لا يستطيع إجراء فحص مسبق لأمر كتابة — يحصل على 403. فالفحص المسبق يجيب عن سؤال «ماذا يحدث إذا استدعيت هذا بهذا المفتاح، الآن»؛ وإعطاء مفتاح القراءة ضوءًا أخضر ثم 403 في الاستدعاء الحقيقي سيكون بالضبط المفاجأة التي وُجد الفحص المسبق لمنعها.
• مفتاح عدم التكرار لا يُستهلك — المفتاح المُرسل أثناء الفحص المسبق لا يفتح أي صف في السجل، ولا يحرّر قفلًا انتهت مدته. لذا أرسل المفتاح الذي تنوي استخدامه فعلًا: إذ يخبرك الفحص المسبق ما إذا كان لا يزال متاحًا، أو سيعيد نتيجة تشغيل سابق (replay)، أو يتعارض مع أمر آخر.
• يمكن دمجه مع confirm — أرسل dry_run و confirm معًا فيصبح السؤال: «إذا أكّدت، فماذا يحدث؟». ومع ذلك لا يُنفَّذ شيء.
• الفحص المسبق للدفعة يكون على مستوى الدفعة كلها — تقبل commands:batch الحقل dry_run أيضًا، لكن العلَم يخص الدفعة لا عنصرًا منها (وإرساله على عنصر يُنتج 422). وتحصل على تقرير لكل عنصر إضافة إلى إجمالي تكلفة الدفعة من الرصيد؛ ويُبلَّغ عن الرصيد غير الكافي دون أن يُرفض الطلب.
• ليس مجانيًا — كل فحص مسبق ينفّذ استعلامات حقيقية (المعاينة، والرصيد) ويُحتسب ضمن حد المعدل. لا تُجرِ فحصًا مسبقًا للكتالوج كله مع كل نشر؛ بل افحص مسبقًا الأوامر التي غيّرتها.

عدم التكرار (idempotency): لماذا لا تُنشئ إعادة المحاولة تكرارات

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

الاستدعاء الذي يحمل idempotency_key يُنفَّذ مرة واحدة على الأكثر. فالاستدعاء الثاني لا يعيد تنفيذ الأمر؛ بل يعيد النتيجة المسجّلة مع الحالة replayed. وعندما تنقطع الشبكة، أو تنتهي مهلة الطلب، أو يلتقط الطابور المهمة نفسها مرتين، تحصل على النتيجة الأولى بدلًا من فاتورة مكرّرة.

استخدم مفتاحًا مع كل أمر كتابة. فالحقل read_only في الكتالوج يمنحك هذا التمييز مجانًا: كل أمر قيمة read_only فيه false يستحق مفتاح عدم تكرار (idempotency key).

ينبغي أن تستخدم استراتيجية إعادة المحاولة لديك التراجع الأسي (exponential backoff) وأن تحمل المفتاح نفسه في كل محاولة. فتوليد مفتاح جديد لكل محاولة يعادل عدم استخدام عدم التكرار على الإطلاق. ولا ترسل المفتاح نفسه بالتوازي: فضمان «مرة واحدة على الأكثر» يسري على إعادات المحاولة المتتابعة، لا على طلبين يتسابقان.

• الفخ 1 — الإخفاق يُقفَل أيضًا — إذا رُفض التنفيذ الأول بسبب قاعدة أعمال (failed)، فإن الاستدعاء الثاني بالمفتاح نفسه يعيد الخطأ نفسه و error_key نفسه، ولا يعيد المحاولة. وتصحيح الوسيط ثم المحاولة مجددًا يتطلبان مفتاحًا جديدًا. فالمفتاح يمثّل محاولة، لا نيّة.
• الفخ 2 — النتيجة الكبيرة تُعاد بلا جسم — لا يخزّن السجل النتيجة إلا إذا كانت أقل من 64 KB. أما النتيجة الأكبر فتُعاد مع الحالة replayed ولكن بجسم فارغ. لذا ينبغي أن يعتمد تكاملك على إشارة «replayed» بدلًا من الجسم، وأن يجلب البيانات عبر أمر get المقابل.
• الفخ 3 — المفتاح يخص أمرًا واحدًا — إرسال المفتاح نفسه مع أمر مختلف يعيد 409 idempotency_conflict مع conflicting_command؛ فلا يُنفَّذ شيء ولا يُعاد شيء. والعميل الذي يتشارك مفتاحًا واحدًا بين فعلين معطوب، ويكتشف ذلك من خطأ صريح، لا من إعادة صامتة.
• الفخ 4 — القفل يدوم 24 ساعة، لا إلى الأبد — بعد 24 ساعة يصبح المفتاح نفسه تنفيذًا جديدًا. فإعادات المحاولة الناتجة عن الشبكة تصل في غضون دقائق؛ وأرقام المستندات التي تتكرر سنويًا في نظام ERP يجب ألا تبقى «replayed» إلى الأبد. وينشر الكتالوج هذه النافذة في الحقل idempotency_ttl_hours.
• الفخ 5 — خطأ الخادم لا يقفل المفتاح — خطأ 5xx من نوع server_error ليس رفضًا من منطق الأعمال: فالمفتاح لا يُربط، لذا فإن إعادة المحاولة بالمفتاح نفسه تشغّل الأمر فعلًا. وحدها الحالة failed تُقفل المفتاح (الفخ 1).
• النطاق والصيغة — شركتك، أي سلسلة نصية، ويُفضَّل UUID — يُفرض التفرّد على الزوج (شركتك، المفتاح): فالمفتاح INV-1001 لدى مستأجر آخر لا يتصادم أبدًا مع مفتاحك ولا يمكنه أبدًا إعادة نتيجتك. استخدم UUID عاديًا أو مفتاحًا مركّبًا فريدًا بحكم بنائه مثل {ERP-document-no}:{verb}.

المزامنة التزايدية وترقيم الصفحات

ينبغي لجسر ERP/CRM أن يسحب ما تغيّر، لا كل شيء كل ساعة. فكل أمر قائمة — loads list و demands list-own و contacts list و invoices list و teammates list و load-groups list و reservations list و drivers list و tenders list و products search و warehouses search — يقبل معاملَين مشتركين ويعيد حقلًا مشتركًا واحدًا.

لماذا لا يوجد offset: في جدول حي تنزاح الإزاحة (offset). فالصف المُدرج بين صفحتين يجعلك تتخطى سجلًا أو تعدّه مرتين، بصمت. أما المؤشر (cursor) فيتقدّم إلى الأمام فقط، لذا فإن السجل المُدرج أو المحدَّث في منتصف المرور يستقر في نهاية القائمة: لا يضيع شيء، ولا يتكرر شيء.

التحميل الأولي الكامل هو الآلية نفسها: ابدأ بـ updated_since=1970-01-01T00:00:00Z وتتبّع next_cursor حتى يصبح null. ولا توجد نقطة نهاية منفصلة لـ «التصدير» لأنه لا حاجة إليها.

الشيء نفسه مع lg: lg loads list --updated_since=2026-09-01T00:00:00Z --limit=100 --json ، ثم lg loads list --cursor= --json.

في المزامنة التالية، اضبط updated_since على أكبر قيمة updated_at رأيتها. ودقة الطوابع الزمنية ثانية واحدة، لذا قد يصل السجل الواقع على الحد مرتين — وهذا غير ضار ما دمت تُجري upsert (إدراجًا أو تحديثًا) حسب external_ref أو code في جانبك. ومن دون updated_since أو cursor يعمل الأمر في وضع المحادثة: ترتيب مخصص للبشر، و 20 صفًا على الأكثر، و next_cursor بقيمة null، و truncated يقول «يوجد المزيد». لا تستخدم هذا الوضع للمزامنة.

مفاتيح الأخطاء المقروءة آليًا لهذا القسم: INVALID_CURSOR و INVALID_UPDATED_SINCE و DUPLICATE_EXTERNAL_REF و EXTERNAL_REF_TOO_LONG و EXTERNAL_REF_INVALID. وجميعها تجيب بـ HTTP 422 مع error_code: "failed" و result.error_key في الجسم. ابنِ التفرّع على المفتاح، لا على النص أبدًا.

• updated_since — طابع زمني بصيغة ISO-8601 (يُوصى بـ UTC، مثل 2026-09-01T00:00:00Z). الصفوف المحدَّثة في هذه اللحظة أو بعدها. ويحوّل الأمر إلى وضع المزامنة: ترتيب ثابت تصاعدي حسب (updated_at, id)، و limit بحد أقصى 100.
• cursor — قيمة next_cursor من الاستجابة السابقة، حرفيًا. وهو مُعتم وموقَّع: لا تبنِ مؤشرًا أو تعدّله أبدًا، ولا تُعِد استخدام مؤشر شركة أخرى أو أمر آخر أبدًا؛ فكل ذلك يُرفض بالخطأ INVALID_CURSOR.
• limit — حجم الصفحة. من 1 إلى 100 في وضع المزامنة (الافتراضي 10).
• next_cursor (في الاستجابة) — مؤشر الصفحة التالية. القيمة null تعني أن القائمة اكتملت؛ وهي الإجابة الصحيحة الوحيدة عن سؤال «هل يوجد المزيد».
• total (في الاستجابة) — عدد الصفوف المطابقة للمرشّحات، بصرف النظر عن الصفحة — لأغراض تقارير التقدّم.

مفتاحك الخاص: external_ref

لا تجعل معرّفاتنا ذات الزيادة التلقائية (invoice_id و contact_id) مفتاح الأعمال في نظام ERP لديك؛ فهي معتمة وخاصة بشركتك. بل تحمل الشحنات والطلبات وجهات الاتصال والفواتير والمنتجات والمستودعات مفتاحك أنت بدلًا منها.

• اضبطه عند الكتابة — تقبل loads create و demands create و contacts create و contacts update و invoices create الحقل الاختياري external_ref (بحد أقصى 120 حرفًا) وتعيده دون تغيير.
• استخدمه عند القراءة — كلها تعمل: loads get --external_ref=ORD-2026-0917 و invoices get --external_ref=... و contacts get --external_ref=... و demands get --external_ref=... ؛ وفي أوامر القوائم والبحث يكون --external_ref= مرشّح مطابقة تامة.
• فريد لكل شركة — يُرفض السجل الثاني الذي يحمل المفتاح نفسه بالرمز 422 مع result.error_key = DUPLICATE_EXTERNAL_REF؛ ومفتاح شركة أخرى يجيبك بـ «غير موجود». والمطابقة غير حساسة لحالة الأحرف (ord-1 = ORD-1). ويحتفظ السجل المؤرشف بمفتاحه؛ فاستعِده قبل إعادة استخدام المفتاح.
• أرسل idempotency_key أيضًا — إعادة المحاولة بعد انتهاء مهلة الشبكة تعيد النتيجة الأولى بدلًا من إنشاء نسخة مكرّرة. والاثنان غير قابلين للتبادل: external_ref هو مفتاح الأعمال الخاص بك، و idempotency_key يعرّف محاولة واحدة.

Webhooks الصادرة: نرسل إليك طلب POST عند وقوع حدث

كل ما سبق كان سحبًا (pull): أنت تسأل ونحن نجيب. فكان على جسر ERP أن يسأل مرة كل دقيقة ليعرف أن شحنة غيّرت حالتها، أو أن فاتورة صدرت، أو أن عرضًا وصل. لم يعد الأمر كذلك: سجّل عنوان https، واختر الأحداث التي تهمك، وسيصلك طلب POST موقَّع عند وقوعها.

أُضيف الدفع (push) إلى جانب السحب، لا بديلًا عنه. فالمزامنة التزايدية (updated_since + cursor) لم تُمس وما تزال الأداة الصحيحة: التحميل الكامل الأول، وتعبئة السجل التاريخي، والإجابة عن سؤال «هل فاتني شيء»، كلها تعيش هناك. أما webhooks فتقلّص زمن الاستجابة من دقائق إلى ثوانٍ. والجسر السليم يستخدم الاثنين — webhook كمُحفّز، والمزامنة كشبكة أمان.

الحمولة (payload) إشارة، لا نسخة من السجل. فهي تحمل المعرّفات (id، و external_ref الخاص بك، والحالة، والوقت)؛ وتجلب التفاصيل بمفتاحك أنت عبر GET، وهذا الاستدعاء يمر أصلًا عبر بوابات التفويض الخاصة بك. لذا يبقى سطح الانكشاف عند مستوى المعرّفات. وهناك حقلان غائبان عن قصد: هوية الشركة التي قدّمت العرض (فالعروض العمياء تظهر باسم مستعار في لوحة التحكم؛ ووضع الهوية في webhook سيخترق هذه الخصوصية عبر قناة ثانية)، وبيانات الاتصال الخاصة بالحجز (فلا حاجة إلى نقل البيانات الشخصية عبر قناة إضافية).

أسماء الأحداث مُجمَّدة. فإذا تغيّر معنى اسم ما، يُفتح اسم جديد ويعيش الاسم القديم خلال نافذة إهمال (deprecation). وإضافة حقل جديد إلى الحمولة لا ترفع إصدار العقد — إذ يجب على المستهلك تجاهل الحقول التي لا يعرفها.

• GET /api/common/integration-webhooks — السجل إضافة إلى كتالوج الأحداث والحدود وأسماء الترويسات. ويحمل كل صف سبب كتمه وملخص تسليمات آخر 7 أيام.
• POST /api/common/integration-webhooks — 201 + { webhook, secret, shown_once: true }. لا يظهر السرّ إلا هنا.
• PATCH /api/common/integration-webhooks/{uuid} — الاسم / العنوان / الأحداث / علَم التفعيل. لا يمس السرّ.
• DELETE /api/common/integration-webhooks/{uuid} — يزيله: يُحذف الصف حذفًا ناعمًا (soft delete) ويبقى السجل التاريخي قابلًا للاستعلام، وتُلغى التسليمات المعلّقة.
• POST /api/common/integration-webhooks/{uuid}/rotate-secret — 201 + سرّ جديد. وتتوقف القيمة القديمة عن العمل في تلك اللحظة.
• POST /api/common/integration-webhooks/{uuid}/test — حدث ping — بتوقيع حقيقي، ومسار حقيقي، وجدول إعادة محاولة حقيقي.
• GET /api/common/integration-webhooks/{uuid}/deliveries — أحدث التسليمات: الحالة، ورقم المحاولة، ورمز HTTP، والمدة، ووسم الخطأ.
• POST /api/common/integration-webhooks/deliveries/{uuid}/replay — يعيد إرسال تسليم واحد: يُحفظ event_id، ويكون معرّف التسليم جديدًا، وتُنسخ الحمولة حرفيًا.

كتالوج الأحداث

كل حدث من الأحداث أدناه البالغ عددها 13 يقابله صنف حدث يُرسَل فعلًا. لا توجد في الكتالوج أسماء من قبيل «سيكون من الجيد وجودها»: فالحدث الذي يُعلَن عنه ولا يُطلق أبدًا هو حدث ينتظره المطوّر المسؤول عن التكامل إلى الأبد، وهذا الإخفاق صامت. وهذا الجدول أيضًا ليس مكتوبًا يدويًا — بل يُستمد من الكتالوج الحي مع كل تحميل للصفحة.

الحدث invoice.payment_recorded غائب عن قصد: فصنف هذا الحدث موجود في الشيفرة لكنه لا يُرسَل من أي مكان. وسيُضاف حدث الدفع في اليوم الذي يُطلق فيه الصنف فعلًا — لا قبل ذلك. فالإعلان عن حدث مبكرًا أسوأ من عدم إضافته أبدًا.

• load.created — A load became visible to your company (created by you or shared with you). (load)
• load.status_changed — A load moved to a new status (pending, in_transport, transit, done). (load)
• load.driver_assigned — A driver was assigned to a load. (load)
• demand.created — A freight demand was created by your company. (demand)
• demand.status_changed — A freight demand changed status. (demand)
• demand_bid.created — A bid was placed on a demand you are party to. (demand_bid)
• demand_bid.revised — A bid was revised (a new revision replaced the previous one). (demand_bid)
• demand_bid.accepted — A bid was accepted. (demand_bid)
• invoice.created — An invoice draft was created. (invoice)
• invoice.issued — An invoice was issued (it now carries an invoice number). (invoice)
• invoice.cancelled — An invoice was cancelled. (invoice)
• warehouse_reservation.created — A warehouse dock/area reservation was created. (warehouse)
• warehouse_reservation.status_changed — A warehouse reservation was approved, rejected or otherwise moved. (warehouse)

التحقق من التوقيع

يحمل كل طلب الترويسة X-Logistivo-Signature: t=,v1=. والسلسلة الموقَّعة هي "." والخوارزمية HMAC-SHA256. وتُبقي البادئة v1 المخطط قابلًا للإصدار: فإذا ظهر مخطط ثانٍ يومًا ما، تحمل الترويسة t=…,v1=…,v2=… وتختار أنت المخطط الذي تعرفه.

ننشر مستقبِلَين مرجعيين بلا تبعيات، أحدهما لـ Node والآخر لـ PHP الخالص. يطبّق كلاهما القواعد الأربع أعلاه ويختبران نفسيهما عبر --selftest: توقيع صالح، وجسم معبوث به، وسرّ خاطئ، وطابع زمني خارج النافذة، وترويسة مشوّهة، وفخ إعادة التسلسل، ونوعا التكرار كلاهما (التسليم نفسه / الواقعة نفسها). والمُحقِّق هو النظير المطابق تمامًا للشيفرة التي نستخدمها نحن — فنحن نستهلك العقد الذي ننشره.

• تحقق من الجسم الخام — يُحسب التوقيع على البايتات. ففك ترميز الجسم ثم إعادة تسلسله (JSON.stringify(req.body), json_encode($request->all())) يحوّل البيانات نفسها إلى بايتات مختلفة فيتوقف التوقيع عن المطابقة. في Node يكمن الفخ في تنسيق الأرقام (1.50 على السلك تصبح 1.5؛ والأعداد الصحيحة الكبيرة تفقد دقتها)، وفي PHP يكمن في تهريب الأحرف (/ تصبح \/، و İ تصبح \u0130). استخدم express.raw في Express و $request->getContent() في Laravel. هذا هو الخطأ الأكثر شيوعًا على الإطلاق عند كتابة مستقبِل (receiver).
• تحقق من الطابع الزمني — القيمة t موجودة داخل التوقيع. والتحقق من التوقيع وحده يتيح لأي شخص التقط طلبًا صالحًا أن يعيد إرساله بعد ساعات، وسيعدّه المستقبِل حدثًا موثَّقًا. لذا أسقط أي طلب يتحقق فيه |now − t| > tolerance حتى لو كان التوقيع صحيحًا. والنافذة الموصى بها 300 ثانية.
• قارن في زمن ثابت — hash_equals / timingSafeEqual. المقارنة باستخدام == تتيح للمهاجم تخمين التوقيع بايتًا بايتًا.
• أزِل التكرار حسب event_id، لا حسب id — يعرّف event_id الواقعة نفسها: فهو متطابق لدى مشتركَين يتلقيان الحدث نفسه، ويُحفَظ عند إعادة الإرسال (replay). أما id (= X-Logistivo-Delivery) فيعرّف التسليم ويتغيّر عند إعادة الإرسال. أجب عن سؤال «هل عالجت هذا من قبل» باستخدام event_id؛ فالإجابة عنه باستخدام id تجعل إعادة الإرسال تنفّذ العمل نفسه مرتين.

التسليم، وإعادة المحاولة، والكتم

لن يكون مستقبِلك متاحًا دائمًا. والمسار يفترض ذلك: فالإخفاق العابر يدخل جدول إعادة المحاولة، والإخفاق الدائم يكتم الاشتراك — ويُسجَّل سبب الكتم دائمًا.

سبب الكتم مقروء آليًا وثابت (delivery_failures و endpoint_gone و unsafe_target و key_revoked و by_user) ويظهر في لوحة التحكم وفي `lg webhooks list` كليهما. فالكتم بلا سبب سيترك سؤال «لماذا لا يصل شيء» بلا إجابة. وإعادة التفعيل تصفّر العدّاد والختم.

أنت تكتب العنوان؛ وخادمنا نحن هو من يرسل الطلب. ومن دون بوابة، يمكن لمستأجر أدخل عنوان بيانات وصفية سحابية (cloud metadata) أن يجعلنا نرسل طلبات من داخل شبكتنا. لذا يُفحص العنوان عند تسجيله وعند كل تسليم:

• المهلات — 8 ثانية إجمالًا، و 4 ثانية للاتصال — فلا يجوز أن يشغل مستقبِل بطيء عاملًا (worker). ضع العمل في طابور وأعِد 2xx فورًا.
• جدول إعادة المحاولة — 60 · 300 · 1800 · 7200 · 21600 ثانية ← بحد أقصى 6 من المحاولات، أي نافذة تقارب 8.6 ساعة.
• الإخفاق الدائم الوحيد: 410 Gone — ويعني «احذفني»: لا إعادة محاولة، ويُكتم الاشتراك فورًا. لا تُعِد 410 أبدًا عند فشل التحقق من التوقيع.
• كل إخفاق آخر — تُعاد محاولتها جميعًا، بما فيها 4xx. فخسارة حدث أعمال أكلف من بضعة طلبات إضافية: فالمستقبِل الذي يعيد 403 أثناء تحديث قاعدة WAF سيخسر بصمت حدث «صدرت فاتورة» على مسار يعامل 4xx على أنها دائمة.
• Retry-After — يُحترم مع 429 و 503 (بحد أقصى 6 ساعات).
• إعادات التوجيه — لا تُتبَع. فالقفز إلى عنوان داخلي عبر 302 سيخترق بوابة العناوين من طريق ثانٍ.
• الكتم التلقائي — بعد 10 من عمليات التسليم المتتالية التي استُنفدت محاولاتها. أما 410، والهدف غير الآمن، وإلغاء مفتاح التكامل المرتبط، فتكتم الاشتراك فورًا.
• https فقط، والمنفذان 443/8443 فقط، وتُرفض بيانات الاعتماد المضمّنة (https://user:pass@…)؛
• تُرفض localhost، والأسماء ذات المقطع الواحد، واللواحق الداخلية مثل .internal / .local / .svc — إذ تُرفض النية قبل النظر في نتيجة الحلّ أصلًا، لذا لا يستطيع DNS ذو الأفق المنقسم (split-horizon) اختراق البوابة؛
• يجب أن تكون عناوين IP الحرفية وجميع سجلات حلّ DNS عامة. فإذا حُلّ اسم إلى عنوان عام وآخر خاص معًا، فلن يسألنا أحد أيهما نختار، لذا يُرفض الاسم مباشرة؛
• عند التسليم يُحلّ العنوان مرة واحدة ويُثبَّت الاتصال على العنوان الذي جرى التحقق منه: فتُغلق نافذة إعادة ربط DNS (DNS rebinding)؛
• لا يُخزَّن جسم استجابة المستقبِل في أي مكان أبدًا (بل رمز الحالة والمدة ووسم خطأ قصير فقط) — لذا يبقى مسار «القراءة»، وهو القيمة الفعلية لأي ثغرة في بوابة العناوين، مغلقًا.
• لا يوجد عن قصد أي مفتاح إعداد لـ «السماح بالعناوين الخاصة»: فمثل هذا المفتاح يُترك مفعّلًا عن طريق الخطأ في يوم ما.
• يُعاد مرة واحدة فقط، عند إنشاء الاشتراك وعند rotate-secret. ويُخزَّن مشفَّرًا على الخادم ولا يمكن قراءته مجددًا أبدًا؛ فلا يوجد «عرض مرة أخرى».
• يطبعه lg على الشاشة ويتركه هناك — ولا يكتبه في أي ملف إعدادات أو ذاكرة تخزين مؤقت.
• إذا فُقد فإنك تدوّره (rotate)؛ وتتوقف القيمة القديمة عن العمل في تلك اللحظة تحديدًا. ولانتقال سلس، ينبغي أن يجرّب مستقبِلك السرّين كليهما خلال فترة الانتقال.
• تغيير العنوان لا يمس السرّ: فالصيانة الروتينية من قبيل «انتقل الـ URL» يجب ألا تكسر التحقق في جهة الاستقبال.

الصحة والحالة: يجب ألا يلاحظ أحدٌ الجسرَ الصامت قبلك

نادرًا ما يموت جسر التكامل بصخب. بل يصمت عادةً في ساعات الفجر الأولى: ينتهي رمز مميز، أو يغادر الفريقَ الشخصُ الذي يعمل المفتاح نيابةً عنه، أو يُضيَّق نطاق صلاحية، أو تبدأ نقطة النهاية المستقبِلة بإعادة 403. وأول من يلاحظ ذلك هو العميل في أغلب الأحيان. ويوجد lg status لعكس هذا الترتيب.

أمر واحد يجيب عن سؤالين في آن واحد، لأن كليهما يُطرح في اللحظة نفسها أثناء الانقطاع: هل المنصة تعمل، وهل جسري سليم. ويعمل سطر المنصة دون رمز مميز — فأثناء العطل يكون الرمز نفسه أول المشتبه بهم، وربط سؤال الحالة به سيتركك بلا إجابة تمامًا حين تحتاج إليها.

لا يحتفظ ملخص الصحة بسجل جديد؛ بل يدمج ثلاثة مصادر قائمة في جملة واحدة: عدّاد الاستخدام اليومي (كم استدعيت وكم فشل)، وسجل الطلبات (أي طلب، ومتى، ولماذا رُفض)، وسجل تسليمات webhooks الصادرة (هل وصل الحدث إلى المستقبِل). ويُقرأ معدل الأخطاء دائمًا من العدّاد اليومي؛ أما سجل التفاصيل فله سقف، ويصرّح بذلك بوضوح عند بلوغه.

يظهر الملخص نفسه في لوحة التحكم: ففي Settings › Integration › Keys يحمل كل صف شارة، وتحتها السبب. ولا تُحسب العتبات في جهة العميل؛ فالمستوى الذي يحدده الخادم هو ما تعرضه لوحة التحكم و lg status كلاهما، لذا لا يمكن أبدًا أن تقول الشاشتان أشياء مختلفة عن المفتاح نفسه.

لا تحتاج أداة المراقبة لديك إلى رمز مميز. تعيد نقطة النهاية كلمات الحالة فقط؛ ولا تحمل أي إصدار أو اسم مضيف أو اسم طابور أو عدد مهام أو نص خطأ أو بيانات عملاء — ولا يمكنها ذلك.

يُنتَج ملخص الصحة بعدد ثابت من الاستعلامات لكل طلب؛ فعدد الاستعلامات لا يزداد بازدياد عدد المفاتيح. وللتفاصيل، اقرأ أحدث طلبات ذلك المفتاح عبر lg logs والجسر الصادر عبر lg webhooks list.

• سليم — لا يوجد عطل مَقيس، ولدينا دليل على النجاح: استدعاء ناجح في السجل، أو حركة طلبات بقيت خالية من الأخطاء في العدّاد.
• انتباه — بدأ شيء ما بالتعطّل: تجاوز معدل الأخطاء أو سلسلة الإخفاقات المتتالية عتبة ما، أو تُرفض الطلبات عند البوابة، أو اقترب المفتاح من انتهاء صلاحيته، أو صمت جسر كان يتواصل بانتظام.
• متعطّل — الجسر لا يعمل الآن: أُلغي الرمز المميز دون قصد، أو لا يزال مفتاح مغلق يُستدعى، أو هناك خمسة إخفاقات متتالية، أو معدل الأخطاء يتجاوز خمسين بالمئة، أو كُتم اشتراك webhook.
• مغلق — أُغلق المفتاح عن قصد ولا أحد يستدعيه. هذا قرار، لا عطل — ولا يُلوَّن بالأحمر.
• لا بيانات — لا يوجد قياس: لم يُستدعَ المفتاح قط، أو فشل القياس نفسه. ولا أيٌّ من الحالتين خضراء.
• لا أخضر زائف. فشارة «سليم» تتطلب دليلًا مَقيسًا على النجاح؛ والمفتاح الذي لم يُستدعَ قط لا يصبح أخضر أبدًا، لأنه لا يوجد قياس واحد يُظهر أنه يعمل.
• لا أحمر زائف. فالمفاتيح التي أغلقتها عن قصد تظهر بحالة «مغلق». وتلوين كل شيء بالأحمر يُفقد الأحمر معناه؛ فالمفتاح المغلق لا يتحول إلى الأحمر إلا إذا ظل يُستدعى بعد إغلاقه — وحينها يكون هناك جسر معطّل فعلًا.
• «تعذّر القياس» ليس هو نفسه «لا بيانات». فإذا فشل استعلام في جهة الخادم، لا يعرض الصف صفرًا بصمت؛ بل يقول إن القياس تعذّر.
• يُبلَّغ عن الصمت دائمًا لكنه لا يتحول أبدًا إلى تحذير بشكل أعمى. فصمت جسر يعمل في نهاية الشهر لمدة ثلاثين ساعة أمر طبيعي؛ أما صمت جسر تواصل في خمسة أيام على الأقل من الأيام السبعة الأخيرة فهو عطل. فالإيقاع يُقاس، ولا يُفترض.
• استعلام الحالة نفسه لا يلوّث أرقام الصحة. فالاستدعاءات التي يجريها lg status تظهر في سجل الطلبات لكنها مستبعدة من حسابات الصحة — وإلا لأعاد استعلام الحالة الناجح الذي تجريه أنت تصفير سلسلة الإخفاقات وأخفى العطل نفسه الذي وُجدت الشاشة لإظهاره.
• كل سطر مَقيس: يُنفَّذ استعلام حقيقي على قاعدة البيانات، ويُبنى كتالوج الأوامر فعلًا، ويُقرأ السجل الحي لعامل الطابور فعلًا. لا شيء مفترض.
• والاستجابة نفسها قياس أيضًا: فإذا استطعت قراءة الجسم، فطبقة الويب تعمل.
• لا يُستمد المستوى الأعلى إلا من المكوّنات الإلزامية. فعندما يتوقف الطابور تكون الإجابة degraded، لا down — فاستدعاء API المتزامن لا يحتاج إلى الطابور، وإعلان توقف المنصة سيكون إنذارًا كاذبًا.
• وعندما يتعذّر قياس حالة الطابور يُترك المستوى الأعلى كما هو: فعدم المعرفة ليس هو نفسه قياس أن شيئًا ما معطّل.
• إذا كانت المنصة متوقفة تعيد نقطة النهاية HTTP 503. والجسم بلا غلاف كي تتمكن أدوات المراقبة من إطلاق التنبيه دون تحليله، ولا تُخزَّن الاستجابة أبدًا في أي ذاكرة تخزين مؤقت.

الأخطاء ورموز الخروج

ما تبني عليه الآلة تفرّعها هو سلسلة نصية ثابتة. أما النص في الحقل error فموجّه إلى البشر، ومترجم حسب اللغة، ويتغيّر دون إشعار — والتكامل الذي يبني تفرّعه على نص الرسالة غير مدعوم، وتعطّله ليس خللًا.

تصنيفان، وحقلان. error_code يمثّل طبقة النقل (الجدول أعلاه) وهو أول ما تبني عليه تفرّعك. أما error_key فهو مفتاح قاعدة الأعمال الثابت داخل الحالة failed — INSUFFICIENT_CREDITS و NOT_FOUND و DUPLICATE_CONTACT و INSUFFICIENT_STOCK — ويُنشر كقاموس في الكتالوج (error_keys) وأدناه. والأمر الذي لا يُصدر مفتاحًا بعد يعيد error_key: null؛ وتعامل مع المفتاح غير الموجود في القاموس على أنه إخفاق عام.

• ok — HTTP 200 · error_code — · CLI 0 · —
• replayed — HTTP 200 · error_code — · CLI 0 · إعادة مع ضمان عدم التكرار (idempotent replay)؛ لم يُنفَّذ العمل مرة أخرى.
• failed — HTTP 422 · error_code failed · CLI 1 · لا — رفضته قاعدة أعمال (انظر error_key). لا جدوى منها إلى أن يتغيّر الوسيط.
• needs_confirmation — HTTP 409 · error_code needs_confirmation · CLI 4 · نعم، مع confirm: true.
• idempotency_conflict — HTTP 409 · error_code idempotency_conflict · CLI 2 · لا — استُخدم المفتاح أولًا مع أمر مختلف (conflicting_command). أنشئ مفتاحًا جديدًا.
• forbidden — HTTP 403 · error_code forbidden · CLI 3 · لا — بوابة الدور، أو مفتاح بنطاق القراءة مع أمر كتابة.
• not_found — HTTP 404 · error_code not_found · CLI 2 · لا — اسم أمر خاطئ أو محذوف.
• (المخطط) — HTTP 422 · error_code invalid_request · CLI 2 · لا — فشل جسم الطلب أو أحد الوسائط في التحقق من المخطط (errors{})؛ وليست قاعدة أعمال.
• server_error — HTTP 500 · error_code server_error · CLI 6 · نعم — مع تراجع أسي (exponential backoff) وبمفتاح عدم التكرار نفسه؛ فالمفتاح لم يُقفل.
• 401 unauthenticated — انتهت صلاحية الرمز المميز أو أُلغي. إعادة المحاولة لن تفيد؛ يجب استبدال الرمز.
• 429 rate_limited — تجاوز هذا الرمز المميز حد المعدل. تحمل الاستجابة دائمًا Retry-After وجسمًا يتضمن retry_after و limit و bucket؛ فالتزم بها بدلًا من اختراع تأخير ثابت. وينتظر lg ويعيد المحاولة حتى ثلاث مرات، ثم يخرج بالرمز 5.
• 5xx server_error / network error — أعِد المحاولة مع تراجع أسي وبمفتاح عدم التكرار نفسه. فتغيير المفتاح يعيد تشغيل عمل ربما أكمله الخادم بالفعل. ويعيد lg المحاولة ثلاث مرات (1 s، 2 s، 4 s)، ثم يخرج بالرمز 6 مع error_code بقيمة network_error أو server_error.

وعد الاستقرار

أغلى سؤال في عقد التكامل هو: «هل ستظل الشيفرة التي أكتبها اليوم تعمل غدًا؟». ويجيب عنه رقم واحد: contract_version في الكتالوج، والترويسة X-Contract-Version في كل استجابة. وهو يجيب عن سؤال واحد بالضبط — هل ما تزال الشيفرة المكتوبة سابقًا تعمل دون تغيير؟ إذا لم يرتفع الرقم، فنعم. وإذا ارتفع، فلا: فقد أُزيل أو ضُيِّق شيء كنت تعتمد عليه.

لأن الإعلان لا يزيل شيئًا: فشيفرتك الحالية تعمل تمامًا كما كانت، في اليوم التالي له. ورفع الإصدار عند الإعلان سيُطلق إشارتين لتغيير واحد ويعوّدك على تجاهل الأولى — مما يُضعف الإشارة المهمة فعلًا. والإعلان يصلك أصلًا مع الاستدعاء الذي تجريه: deprecated_at و replaced_by في صف الكتالوج، وترويسة X-Deprecated إضافة إلى كتلة deprecated في استجابة ذلك الأمر، وتحذير من سطر واحد في stderr إذا كنت تستخدم lg. لا يتعين عليك فعل أي شيء لتعرف أن شيئًا ما في طريقه إلى الزوال؛ فهو موجود أصلًا في سجلك.

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

preview_invoice → get_invoice (أُعلن عنها في 3 سبتمبر 2026). يعيد get_invoice كتلة المعاينة نفسها ويضيف البنود، وتفصيل الضرائب، والمدفوعات المسجّلة، والرصيد المتبقي، وإمكانية الوصول عبر مفتاح ERP الخاص بك (external_ref). ويظل preview_invoice يعمل، وكذلك lg invoices preview — وكلاهما ينبّه.

• لا تغيير — أمر جديد · معامل اختياري جديد · حقل استجابة جديد · مفتاح خطأ جديد · نقطة نهاية جديدة — لا تفعل شيئًا. يجب أن تتجاهل الحقول التي لا تعرفها؛ والمحلّل الذي يفشل عند حقل غير معروف غير مطابق للعقد.
• لا تغيير — إعلان إهمال: إشعار بأن أمرًا ما في طريقه إلى الإزالة — تستمر شيفرتك في العمل. ضع مهمة في تقويمك — فالنافذة 6 أشهر على الأقل.
• يرتفع — إزالة أمر · إحالة اسم CLI قديم إلى التقاعد · إسقاط حقل استجابة · جعل معامل اختياري إلزاميًا · تضييق قيم enum — يعني ذلك أنك فوّت النافذة؛ فقد وصلك الإشعار في ثلاثة أماكن منفصلة.
• اسم API للأمر (مثل list_loads) مُجمَّد إلى الأبد؛ وهو الاسم الذي تستخدمه في استدعاءات HTTP.
• error_code (النقل) و error_key (قاعدة الأعمال) سلاسل نصية ثابتة. وقد تظهر قيم جديدة — فتعامل مع المفتاح الذي لا تجده في القاموس على أنه إخفاق عام، لا على أنه كسر للعقد.
• التطابق بين حالة HTTP والحقل status في الجسم ثابت.
• رقم الإصدار لا ينخفض أبدًا، ويمكن قراءته في كل استجابة — بما فيها 304 و 429 بلا جسم.
• نص الأخطاء والأوصاف. فهو مترجم حسب اللغة ويتغيّر دون إشعار؛ وبناء التفرّع على نص الرسالة غير مدعوم.
• غياب الحقول التي لا تعرفها. فإضافة حقل لا ترفع الإصدار.
• المعرّفات ذات الزيادة التلقائية كمفاتيح أعمال. احمل مفتاحك الخاص عبر external_ref.
• مفاتيح الأخطاء الديناميكية المشتقة من أسماء الأصناف؛ فهي ليست جزءًا من العقد.

جدول هوية الأوامر

الجدول أدناه ليس مكتوبًا يدويًا: بل يُولَّد من سجل الأوامر الحي في كل مرة تُقدَّم فيها هذه الصفحة. والأمر المضاف على الخادم يظهر هنا تلقائيًا. ويخبرك عمود «البوابة» ما إذا كان الأمر يطلب تأكيدًا وما إذا كان يمكن التراجع عن أثره؛ ويخبرك عمود «الأدوار» بأنواع الحسابات التي ستجده في كتالوجها. وتميّز الشارات الأوامر التي تحتاج إلى مفتاح بمستوى manager، والأوامر التي تأخذ ملفًا، والأوامر التي لا تعمل إلا من lg.

اسم API (list_loads) مُجمَّد ولن يتغيّر؛ وهو الاسم الذي تستخدمه في استدعاءات HTTP. أما هوية CLI (loads list) فتحكمها سياسة الإصدارات: فبعد الإعلان عنها لا تتغيّر إلا مع رفع الإصدار ونافذة ترحيل، يقدّم الكتالوج خلالها الزوج القديم كاسم مستعار (alias). والأوصاف هنا مأخوذة من سجل كل أمر ومختصرة — وللاطلاع على النص الكامل وأنواع المعاملات وقيم enum، اقرأ نقطة نهاية الكتالوج أو شغّل lg help . ولا تُدرج هنا الأوامر الخاصة بحسابات الشريك بالإحالة (affiliate) وحدها؛ إذ يراها حساب الشريك بالإحالة في كتالوجه الخاص.

• lg account-settings get — Read the account settings (Settings → Account): the company display name (and legal name, read-only), the signed-in user's own name and e-mail (e-mail is read-only here), the saved load code prefix and how the company… (قراءة · — · شاحن · API: get_account_settings) [مفتاح manager]
• lg account-settings update — Change account settings (Settings → Account): company_name (the company's display name, company-wide), first_name / last_name (the signed-in user's own name — when only one is given the other part is kept),… (كتابة · تأكيد · شاحن · API: update_account_settings) [مفتاح manager]
• lg accounting-settings get — Read the company's accounting and invoicing settings and say whether they are set up (muhasebe ayarları, fatura ayarları, e-fatura / e-invoice profile, KDV / VAT tax regime, fatura numaralandırma serisi / invoice… (قراءة · — · الكل · API: get_accounting_settings)
• lg accounting-settings set-status — Turn the company's accounting module on or off (muhasebe modülünü aç/kapa). (كتابة · تأكيد · الكل · API: set_accounting_module)
• lg accounting-settings update — Update the company's accounting/invoicing settings (muhasebe ve fatura ayarlarını değiştir): legal name, default currency, provider (local/parasut), country, tax regime (KDV/VAT/GST/none), default invoice line… (كتابة · تأكيد · الكل · API: update_accounting_settings)
• lg addresses list — Loading and delivery addresses already used on this company's previous loads (newest first): address_id, name, street, city and country. query filters by name, street or city. limit 1-50 (default 20). (قراءة · — · الكل · API: list_worked_addresses)
• lg addresses search — Find a place for a route plan stop: the company's own address book first, then a geocoder (counted against the daily routing allowance) when the book has fewer than 3 hits. (قراءة · — · ناقل · API: lookup_address)
• lg ai-settings get — Read our company's AI switches (Settings → AI), e.g. ai_file_classify ("AI document analysis"): whether files posted into our load chats are read by AI, sorted into document types and split into company documents, or… (قراءة · — · شاحن · API: get_ai_settings) [مفتاح manager]
• lg ai-settings update — Turn our company's AI switches on or off (Settings → AI) — e.g. "stop AI from analysing the files in our load chats" → settings=[{"slug":"ai_file_classify","enabled":false}]. settings is a list of {slug, enabled}; slugs… (كتابة · تأكيد · شاحن · API: update_ai_settings) [مفتاح manager]
• lg announcements list — Show the system announcements Logistivo sent to this user (new features, maintenance, policy changes) — newest first. (قراءة · — · الكل · API: list_announcements)
• lg announcements mark-read — Mark system announcements as read for this user. (كتابة · — · الكل · API: mark_announcements_read)
• lg attachments get — Read a file the user attached to THIS conversation (listed in the user message as [Attachments] with their attachment_uuid). (قراءة · — · الكل · API: read_attachment) [يأخذ ملفًا: attachment_uuid]
• lg background-jobs get — Check a background job that another command queued and returned a job_id for (document consistency re-analysis, file classification, tariff inquiry, tariff invoice reading, receipt pack…): status pending / running /… (قراءة · — · الكل · API: get_background_job)
• lg bank-accounts create — Add one of YOUR OWN company bank accounts to the account book (the accounts you get paid into). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: create_company_bank_account) [مفتاح manager]
• lg bank-accounts delete — Delete one of OUR OWN company bank accounts (for example a closed account). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_company_bank_account) [مفتاح manager]
• lg bank-accounts extract — Read a supplier's bank accounts (IBAN, bank, holder, currency) from one of ITS invoices and save them on that business contact. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: extract_supplier_bank_accounts) [يأخذ ملفًا: attachment_uuid]
• lg bank-accounts list — List bank accounts. (قراءة · — · الكل · API: list_bank_accounts)
• lg bank-accounts preview — Check an IBAN without saving anything: is it valid (country, length, checksum) and which bank it belongs to (detected offline from the bank code where known). (قراءة · — · الكل · API: preview_bank_account_iban)
• lg bank-accounts set-default — Make one of OUR OWN bank accounts the default — the IBAN printed on our invoices and e-invoices. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: set_default_company_bank_account) [مفتاح manager]
• lg bank-accounts set-status — Confirm or reject a bank account that was read from a document by AI or written by an integration — your own account or a business contact's account (find the ones waiting with list_bank_accounts… (كتابة · تأكيد + غير قابل للتراجع · الكل · API: decide_bank_account_verification) [مفتاح manager]
• lg bank-accounts update — Update one of OUR OWN company bank accounts (the accounts customers pay us into): IBAN, bank, account holder, branch code, account number or currency. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: update_company_bank_account) [مفتاح manager]
• lg banks list — List the banks of Turkey with their bank_id and SWIFT/BIC code — the bank_id that create_company_bank_account and update_company_bank_account need. (قراءة · — · الكل · API: list_banks)
• lg bids accept — Accept a carrier's bid on one of this company's demands. (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: accept_demand_bid)
• lg bids calculate — Before bidding: what this carrier would earn and how many credits a bid would cost if the customer accepts it. (قراءة · — · ناقل · API: calculate_bid_earnings)
• lg bids cancel — Withdraw (geri çek) one of THIS carrier company's PENDING bids. (كتابة · تأكيد + غير قابل للتراجع · ناقل · API: cancel_demand_bid)
• lg bids create — Submit a bid (teklif ver) on an open demand. amount_per_vehicle is the freight PER VEHICLE, not the total. (كتابة · تأكيد + غير قابل للتراجع · ناقل · API: create_demand_bid)
• lg bids get — Detail of ONE bid this carrier company submitted: demand, status (pending / accepted / revised / cancelled / price_too_high), price per vehicle and total, currency, vehicle count, customs included or customs price,… (قراءة · — · ناقل · API: get_my_demand_bid)
• lg bids list — List the bids (teklif) THIS carrier company has submitted, newest first, with their outcome. (قراءة · — · ناقل · API: list_my_bids)
• lg bids revise — Revise this carrier's own PENDING bid on a demand: the old bid is marked revised and a NEW bid replaces it (it gets a new bid code). (كتابة · تأكيد + غير قابل للتراجع · ناقل · API: revise_demand_bid)
• lg carbon-reports calculate — Calculate the CO2 emission of an EXISTING load (load_code: weight and route from the load, including its Ro-Ro leg) OR of a route you describe (transport_mode road|roro + weight_kg + departure_address + arrival_address,… (قراءة · — · الكل · API: calculate_load_carbon_emission)
• lg carbon-reports download — Export ALL of the company's saved CO2 emission reports to one Excel file (one row per report: date, route, mode, weight, distance, emission, factor, method) and return a short-lived download link. (قراءة · — · الكل · API: export_carbon_emission_reports)
• lg carbon-reports generate — Produce the signed CO2 emission report (PDF, with QR code) for a load OR for a route, save it to the company's report list and return a download link. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: generate_carbon_emission_report)
• lg carbon-reports get — Read one CO2 emission report in full: total emission in kg, transport mode, weight, distance, emission factor, calculation method and source, the departure/arrival addresses, the leg breakdown for multi-modal routes… (قراءة · — · الكل · API: get_carbon_emission_report)
• lg carbon-reports list — List the CO2 emission reports this company has generated (newest first): report number, file name, who created it and when. (قراءة · — · الكل · API: list_carbon_emission_reports)
• lg carrier-routes get — This carrier's route definitions (Rota Yönetimi): the countries served — always ↔ Türkiye in both directions — and the vehicle types and load types operated, with ids and names. (قراءة · — · ناقل · API: get_carrier_routes)
• lg carrier-routes set — REPLACE this carrier's route definitions (Rota Yönetimi) with the given FULL sets: countries served (each to/from Türkiye, both directions), vehicle types and load types. (كتابة · تأكيد · ناقل · API: set_carrier_routes) [مفتاح manager]
• lg chart-of-accounts list — List the chart of accounts available to this company (Turkish uniform chart: 100 Kasa, 102 Bankalar, 120 Alıcılar, 320 Satıcılar, 391 Hesaplanan KDV, 600/601 Satışlar…), optionally filtered by code/name text or type. (قراءة · — · الكل · API: list_chart_of_accounts)
• lg checks assign-invoices — Allocate a pending, field-confirmed cheque to one or more open LOCAL invoices of the same contact and currency: in = sales invoices (collection), out = purchase invoices (payment). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: attach_check_to_invoices) [مفتاح manager]
• lg checks bounce — Record that a cheque BOUNCED (came back unpaid). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: mark_check_bounced)
• lg checks cancel — CANCEL a pending cheque (e.g. registered by mistake, returned before use): no journal entry is written and any invoice reservation is released. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: cancel_settlement_check) [مفتاح manager]
• lg checks collect — Record that a cheque was COLLECTED (money reached the bank for an incoming cheque, or left the bank for an outgoing one) on its due date. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: mark_check_collected)
• lg checks create — Register a cheque in the cheque portfolio. (كتابة · تأكيد · الكل · API: create_settlement_check) [مفتاح manager] [يأخذ ملفًا: front_attachment_uuid, back_attachment_uuid]
• lg checks get — Read one cheque in full: its identity (number, serial, bank and branch, drawer with tax number, IBAN), the face amount and currency, issue and due dates, the counterparty, the status with every timestamp (executed,… (قراءة · — · الكل · API: get_settlement_check)
• lg checks list — List the cheque portfolio of this company: cheque number, direction (in = received from a customer, out = given to a supplier), drawer and bank, face amount with its currency, issue and DUE date, the counterparty… (قراءة · — · الكل · API: list_settlement_checks)
• lg checks remove-invoices — Release a pending cheque's invoice allocation: the reservations are removed (invoices become payable again) and the cheque goes back to the unallocated pending cheques. (كتابة · تأكيد · الكل · API: detach_check_from_invoices) [مفتاح manager]
• lg checks run — EXECUTE a pending, allocated cheque against its invoices: the reservations become payments (the invoice balances close), and the notes receivable (121, received cheque) or notes payable (321, given cheque) journal… (كتابة · تأكيد + غير قابل للتراجع · الكل · API: execute_settlement_check) [مفتاح manager]
• lg checks update — Correct a pending cheque's fields and CONFIRM them — the human sign-off on what AI read from the photo (or on a manual entry). (كتابة · تأكيد · الكل · API: update_settlement_check) [مفتاح manager]
• lg companies add-role — Add a role to this company (firmaya rol ekle): customer (shipper), carrier, customs (customs broker) or affiliate. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: add_company_role) [مفتاح manager]
• lg companies delete-logo — Remove this company's logo (firma logosu) from the branded login portal, documents and the panel. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_company_logo) [مفتاح manager]
• lg companies get — This company's own profile (firma profili): legal name, tax number and tax office, address and postal code, city/country, payment term (vade), the company roles it has (customer/carrier/customs/affiliate) and the roles… (قراءة · — · الكل · API: get_company_profile)
• lg companies invite — Invite a company that is NOT on Logistivo yet by e-mail (e.g. a carrier we want to give a load to). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: invite_company_to_platform)
• lg companies list — Logistivo platform companies this company has already worked with on loads (shared load chats), by company_type: customer (shippers), carrier or customs (customs brokers). (قراءة · — · الكل · API: list_platform_companies)
• lg companies search — Check whether a company is on Logistivo — by EXACTLY ONE of: tax_number (exact VKN / tax id), vat_number (exact EU/UK VAT number) or email (any e-mail of that company, matched by its domain; then company_type is… (قراءة · — · الكل · API: search_platform_companies)
• lg companies set-brand-colors — Set the two colours of this company's branded login portal (markalı giriş portalı, /p//login) — primary_color and secondary_color as #RRGGBB hex. (كتابة · تأكيد · ناقل, مخلّص جمركي · API: set_company_brand_colors) [مفتاح manager]
• lg companies set-logo — Make an uploaded image this company's logo (firma logosu) — shown on the branded login portal, documents and the panel. attachment_uuid is a JPEG or PNG image (max 8 MB) uploaded to this conversation or with `lg upload`. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: set_company_logo) [مفتاح manager] [يأخذ ملفًا: attachment_uuid]
• lg companies update — Update this company's profile (firma profili) — send ONLY the fields that change: legal_name (ticaret unvanı), tax_number (VKN / VAT id), tax_branch (vergi dairesi), address_street, postal_code, city_id, country_code… (كتابة · تأكيد · الكل · API: update_company_profile) [مفتاح manager]
• lg company-documents create — File a document the user attached (in this chat, or uploaded to the command surface) as one of the company's own documents (firma evrakı yükle): tax certificate (vergi levhası), signature circulars (imza sirküleri),… (كتابة · تأكيد · الكل · API: upload_company_document) [يأخذ ملفًا: attachment_uuid]
• lg company-documents delete — Remove one of the company's own documents (tax certificate, signature circular, trade registry gazette, permits…) from its document list — e.g. a wrong or outdated upload. document_id is the one shown by… (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_company_document)
• lg company-documents list — List this company's own filed documents (tax certificate, signature circulars, trade registry gazette, contracts, TIO/L2 permits, files uploaded to chats…) with their type, number, validity date and verification status. (قراءة · — · الكل · API: list_company_documents)
• lg company-documents list-missing — Which company documents (tax certificate, signature circulars, trade registry gazette, TIO/L2/C2 permits …) this company is REQUIRED to have for its company type and country, which of them are on file and verified, and… (قراءة · — · الكل · API: list_missing_company_documents)
• lg company-domains create — Add an e-mail domain to our company (e.g. firma.com.tr) and e-mail a 6-digit verification code to a mailbox ON that domain. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: create_company_domain) [مفتاح manager]
• lg company-domains delete — Remove one of our UNVERIFIED company domains (e.g. added by mistake). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_company_domain) [مفتاح manager]
• lg company-domains list — List our company's e-mail domains (Company settings → Domains): each row has company_domain_id, domain, verified (true once the 6-digit code was entered) and, for unverified ones, the mailbox the last code was sent to. (قراءة · — · الكل · API: list_company_domains)
• lg company-domains resend — E-mail a NEW 6-digit verification code for one of our unverified company domains (the previous code stops working). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: resend_company_domain_code) [مفتاح manager]
• lg company-domains verify — Verify one of our unverified company domains with the 6-digit code that was e-mailed to the mailbox on that domain. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: verify_company_domain) [مفتاح manager]
• lg company-relationships accept — Accept a connection proposal another company sent us (relationship_id from list_company_relationships direction=incoming). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: accept_company_relationship) [مفتاح manager]
• lg company-relationships create — Send a connection proposal to link one of our business contacts with its company on the Logistivo platform (company_id from search_platform_companies). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: create_company_relationship) [مفتاح manager]
• lg company-relationships list — List our company connections on the platform (direction=outgoing, default: the connections in our directory, with status and roles such as carrier/customs_broker/supplier) or the connection proposals other companies… (قراءة · — · الكل · API: list_company_relationships)
• lg company-relationships reject — Reject a connection proposal another company sent us (relationship_id from list_company_relationships direction=incoming). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: reject_company_relationship) [مفتاح manager]
• lg company-relationships revoke — End a company connection we are a party of (either side may end it), or withdraw a pending proposal. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: revoke_company_relationship) [مفتاح manager]
• lg contacts add-address — Add an address to a business contact (e.g. a warehouse or branch): a label, the full street address and the country (ISO-2 code); postal code optional. (كتابة · تأكيد · الكل · API: add_business_contact_address)
• lg contacts add-bank-account — Add a bank account (IBAN) to a business contact so it can be used on payment instructions and invoices. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: add_business_contact_bank_account)
• lg contacts add-person — Add a person (yetkili kişi) to a business contact: first name, last name and e-mail are required; phone, phone country code, job title and a note are optional. (كتابة · تأكيد · الكل · API: add_business_contact_person)
• lg contacts archive — Archive a business contact (cariyi arşivle): it disappears from lists and pickers and becomes read-only, but nothing is deleted — invoices, loads and bank accounts stay linked, and restore_business_contact brings it… (كتابة · تأكيد · الكل · API: archive_business_contact)
• lg contacts create — Create a new business contact (cari) in the company directory. (كتابة · تأكيد · الكل · API: create_business_contact)
• lg contacts delete-address — Delete one of a business contact's addresses. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_business_contact_address)
• lg contacts delete-bank-account — Delete one of a business contact's bank accounts (for example an old or wrong IBAN). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_business_contact_bank_account)
• lg contacts delete-person — Delete a person from a business contact, together with that person's notification preferences. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_business_contact_person)
• lg contacts extract — Read a business card, letterhead or invoice header (image or PDF) and return the company details on it — legal name, tax number and office, VAT number, e-mail, phone, IBAN (checksum-checked, bank detected), address,… (قراءة · — · الكل · API: extract_business_contact_from_image) [يأخذ ملفًا: attachment_uuid]
• lg contacts extract-text — Read pasted text (Excel/CSV rows, e-mail signatures, a typed list) and return up to 100 draft records of ONE kind: companies, persons, addresses or bank_accounts. (قراءة · — · الكل · API: extract_business_contacts_from_text)
• lg contacts get — Read one business contact in full (identity, tax data, address, e-mail/phone, bank accounts, platform link) together with its account summary: ledger balance (positive = they owe us), open receivables and open payables. (قراءة · — · الكل · API: get_business_contact)
• lg contacts invite — Invite a business contact to join Logistivo by e-mail. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: invite_business_contact)
• lg contacts list — List the company's business contacts (customers, carriers, suppliers, consignees) with optional text search over name, legal name and tax number. (قراءة · — · الكل · API: list_business_contacts)
• lg contacts list-addresses — List the saved addresses of one business contact (label, street address, postal code, country) with address_id, needed by update/delete. (قراءة · — · الكل · API: list_business_contact_addresses)
• lg contacts list-person-notifications — Show which load notifications a contact person receives and on which channel (e-mail, push, SMS), plus the notification types that can be chosen with their allowed channels — use those slugs with… (قراءة · — · الكل · API: list_business_contact_person_notifications)
• lg contacts list-persons — List the people (yetkili kişiler) saved on one business contact: name, e-mail, phone, job title, note, and which load notifications each one receives. (قراءة · — · الكل · API: list_business_contact_persons)
• lg contacts list-routes — Show which countries a business contact that is linked to a carrier on the platform serves: its declared route pairs (from-country → to-country) and the distinct country list. (قراءة · — · الكل · API: list_business_contact_routes)
• lg contacts remove-company-link — Remove the link between a business contact and its company on the Logistivo platform. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: unlink_business_contact_company) [مفتاح manager]
• lg contacts restore — Bring an archived business contact back (cariyi arşivden geri al): it returns to lists and pickers and can be edited again. (كتابة · تأكيد · الكل · API: restore_business_contact)
• lg contacts search — Resolve a business contact (customer/partner/recipient) by name, legal name or tax number to its contact_id. (قراءة · — · الكل · API: lookup_business_contact)
• lg contacts set-default-bank-account — Make one of a business contact's bank accounts its DEFAULT account — the one pre-selected when you pay this contact. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: set_default_business_contact_bank_account)
• lg contacts set-person-notifications — Turn load notifications on or off for a contact person, per notification type and channel (e-mail, push, SMS). (كتابة · تأكيد · الكل · API: set_business_contact_person_notifications)
• lg contacts update — Update fields of an existing business contact. (كتابة · تأكيد · الكل · API: update_business_contact)
• lg contacts update-address — Correct one of a business contact's addresses. (كتابة · تأكيد · الكل · API: update_business_contact_address)
• lg contacts update-bank-account — Correct one of a business contact's bank accounts: IBAN, account holder, bank name, BIC/SWIFT, currency, label, account type, branch code or account number. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: update_business_contact_bank_account)
• lg contacts update-person — Correct a contact person's details. (كتابة · تأكيد · الكل · API: update_business_contact_person)
• lg containers calculate — Decode and validate a container number (konteyner numarası) per ISO 6346 — owner code, category, serial, check digit (is it correct, and what it should be) and, when known, the operating line with its public tracking… (قراءة · — · الكل · API: decode_container_number)
• lg conversations add-file — Post a file into an OFFER (demand-bid) chat as this user — e.g. a price sheet or a vehicle photo for the other company. conversation_code comes from list_conversations (rows whose subject is demand_bid). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: send_conversation_file) [يأخذ ملفًا: attachment_uuid]
• lg conversations add-invitation — Invite a person from ANOTHER company into a load chat by e-mail (sohbete dışarıdan davet). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: invite_to_conversation)
• lg conversations add-message — Post a message into a load/bid conversation AS THIS USER (not as an assistant). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: send_conversation_message)
• lg conversations add-participants — Add people to a load/demand conversation (sohbete kişi ekle) — "Ayşe'yi FKZ8515 sohbetine ekle". (كتابة · تأكيد · الكل · API: add_conversation_participants)
• lg conversations create — Open the freight chat with a carrier that bid on one of OUR demands (navlun sohbetini başlat) — bid_code comes from get_demand / the bids of a demand. (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: start_bid_conversation)
• lg conversations list — List the chat conversations this user is a member of (load chats, bid chats and private carrier channels), newest activity first. (قراءة · — · الكل · API: list_conversations)
• lg conversations list-files — List the files shared in a load/bid chat, newest first: document type, title, file name, who posted it and when. (قراءة · — · الكل · API: list_conversation_files)
• lg conversations list-invitations — Show the e-mail invitations to a load chat that have not been accepted yet: who was invited, by whom and when, and what they will be allowed to see. (قراءة · — · الكل · API: list_conversation_invitations)
• lg conversations list-messages — Read the most recent messages of one conversation — give it a load code (e.g. (قراءة · — · الكل · API: list_conversation_messages)
• lg conversations list-participants — Who is in this conversation — name and company of every participant. (قراءة · — · الكل · API: list_conversation_participants)
• lg conversations mark-read — Mark one conversation as read for this user (clears its unread badge), or with all=true every load, bid and direct-message chat at once. (كتابة · — · الكل · API: mark_conversation_read)
• lg conversations remove-message — Delete one of THIS user's own messages from a conversation (message_id from list_conversation_messages with `mine` true). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_conversation_message)
• lg conversations remove-participant — Remove someone from a load/bid chat, cancel a pending e-mail invitation to it, or leave it yourself (give your own user_id). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: remove_conversation_participant)
• lg conversations update-message — Edit one of THIS user's own messages in a conversation (message_id comes from list_conversation_messages, where `mine` is true). (كتابة · تأكيد · الكل · API: update_conversation_message)
• lg countries search — Resolve a country by name (Turkish, English or the local/native name) or ISO 3166-1 alpha-2 code to its country_id, for the sending/receiving country on a load. (قراءة · — · الكل · API: lookup_country)
• lg currencies list — The currencies the platform knows (currency_id, code, name, symbol) with the latest exchange rate against the Turkish lira (buying / selling, rate date). currency_id is what forms such as bank accounts take. (قراءة · — · الكل · API: list_currencies)
• lg custom-reports generate — Custom report counted server-side over ALL records of a dataset: filter, group (dates by month etc.), count/sum/avg/min/max (money per currency) or list rows; format=xlsx|pdf|csv gives a file. (قراءة · — · الكل · API: build_report)
• lg customs-companies list — Customs broker companies this customer can assign when accepting a bid (accept_demand_bid customs_company_id): the Logistivo customs companies you already work with in your chats. (قراءة · — · شاحن · API: list_customs_companies)
• lg customs-locations search — Search customs offices / customs locations (gümrük müdürlüğü, gümrük lokasyonu) by name or street — for the exit and destination customs of a load. (قراءة · — · الكل · API: lookup_customs_location)
• lg demand-bid-reports get — Bid report across ALL demands at once, counted server-side: for a customer the bids RECEIVED on its demands, for a carrier the bids it PLACED. (قراءة · — · شاحن, ناقل · API: get_demand_bid_report)
• lg demand-reports get — Demand report (Talep Raporu) with optional filters: status, demanding company, transport mode, pickup / delivery countries, loading-date window. (قراءة · — · شاحن, ناقل · API: get_demand_report)
• lg demand-settings get — This carrier company's demand settings: whether demands opened by forwarder companies reach the company (accept_demands_from_forwarders). (قراءة · — · ناقل · API: get_demand_settings) [مفتاح manager]
• lg demand-settings update — Change this carrier company's demand settings. accept_demands_from_forwarders=false stops demands opened by forwarder companies from reaching the company (only shippers' demands remain); true lets them in again. (كتابة · تأكيد · ناقل · API: update_demand_settings) [مفتاح manager]
• lg demand-targets search — Resolve a pickup/delivery location for a demand to a target token ("5-" = district/postal area, "10-" = seaport address). (قراءة · — · شاحن · API: lookup_demand_target)
• lg demands create — Open a freight demand (talep) so carriers can bid. (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: create_demand) [يأخذ ملفًا: attachment_uuids]
• lg demands download — File for ONE demand owned by this company. export_type=details_pdf: the demand's detail sheet (route, dates, cargo, pallets) as PDF. export_type=sales_xlsx: the sales report workbook — demand information, every bid… (قراءة · — · شاحن · API: download_demand_export)
• lg demands extract — Read a freight request text (an e-mail body, a note, a voice transcript) and return the demand fields it contains in the demand wizard's shape: transport mode, countries, ports, locations, dates, load type, vehicle… (قراءة · — · شاحن · API: extract_demand_from_text)
• lg demands get — Detail of ONE freight demand. (قراءة · — · شاحن, ناقل · API: get_demand)
• lg demands list — List freight demands (talep) this carrier is allowed to bid on, newest first. (قراءة · — · ناقل · API: list_open_demands)
• lg demands list-own — List the freight demands (talep) OWNED by this customer company, newest first, with route, dates, vehicles, status and bid count. (قراءة · — · شاحن · API: list_demands)
• lg demands options — Reference lists needed to build a freight demand (talep) with create_demand: vehicle types (id, name, transport mode), payment maturity options (id + days; company_default_maturity_option_id is what the company normally… (قراءة · — · شاحن · API: get_demand_form_options)
• lg demands set-status — Close (make passive) one of this company's ACTIVE demands so carriers stop bidding. (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: close_demand)
• lg demands update — Edit one of this company's ACTIVE demands that has NO bids yet (a demand with bids or a closed one cannot be edited). (كتابة · تأكيد · شاحن · API: update_demand) [يأخذ ملفًا: attachment_uuids]
• lg direct-conversations add-message — Send a direct message AS THIS USER (never as an assistant) — either into an existing chat (conversation_code from list_direct_conversations) or to one person (to_user_id from list_direct_message_contacts; their private… (كتابة · تأكيد + غير قابل للتراجع · الكل · API: send_direct_message)
• lg direct-conversations create — Start a direct chat. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: create_direct_conversation)
• lg direct-conversations download — Produce the whole direct-message or group chat as a PDF (the same file as the panel's export button: participants and every message with date and time) and return a short-lived download link. (قراءة · — · الكل · API: export_direct_conversation_pdf)
• lg direct-conversations list — List this user's direct-message (DM) chats and group chats — person-to-person messaging, separate from load/bid chats (those are list_conversations). (قراءة · — · الكل · API: list_direct_conversations)
• lg direct-conversations list-contacts — List the people this user can direct-message: their own teammates plus people they share a load/bid chat with. (قراءة · — · الكل · API: list_direct_message_contacts)
• lg direct-conversations list-messages — Read the latest messages of one direct-message or group chat (conversation_code from list_direct_conversations), oldest→newest, with who wrote them. `mine: true` marks this user's own messages; only those, and only… (قراءة · — · الكل · API: list_direct_conversation_messages)
• lg direct-conversations mark-read — Mark one direct-message or group chat as read for this user (clears its unread badge). (كتابة · — · الكل · API: mark_direct_conversation_read)
• lg direct-conversations remove-message — Delete one of THIS user's own direct messages (message_id from list_direct_conversation_messages, mine and editable true), only within 5 minutes of sending. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_direct_message)
• lg direct-conversations update — Rename a GROUP direct chat (private one-to-one chats have no title). (كتابة · تأكيد · الكل · API: rename_direct_conversation)
• lg direct-conversations update-message — Edit one of THIS user's own direct messages (message_id from list_direct_conversation_messages, where mine and editable are true). (كتابة · تأكيد · الكل · API: update_direct_message)
• lg document-checks run — Cross-check documents the user attached to THIS conversation against each other and report the discrepancies: mismatched party names, quantities, weights, amounts, dates, container or reference numbers between an… (كتابة · — · الكل · API: check_document_compliance) [يأخذ ملفًا: attachment_uuids]
• lg document-types list — List the platform's document types (slug and name) — the values document_type_slug accepts in upload_company_document, add_driver_document and the vehicle document commands. (قراءة · — · الكل · API: list_document_types)
• lg documents download — Get a short-lived (15 minute) download/preview link for one document by its document_id (from list_load_documents or list_company_documents). (قراءة · — · الكل · API: get_document_link)
• lg drive-rest-estimates get — One driver's GPS-ESTIMATED driving/rest status and driving time left under EU 561/2006 / AETR: current activity and since when, driving_left_today_s = the legal driving time left today under the daily, weekly (56 h) AND… (قراءة · — · ناقل · API: get_driver_drive_rest_estimate)
• lg drive-rest-estimates list — Fleet overview of the GPS-ESTIMATED driving/rest status and driving time left (EU 561/2006 / AETR): per driver the current activity, driving_left_today_s = the legal driving time left today under the daily, weekly (56… (قراءة · — · ناقل · API: list_driver_drive_rest_estimates)
• lg driver-accounts get — Answer "how much do we owe this driver / how much does the driver owe us". (قراءة · — · شاحن, ناقل · API: get_driver_account_summary)
• lg driver-accounts list-candidates — Before opening or filling a driver settlement statement: which of ONE driver's receipts and advances can go on it, and why the others cannot. (قراءة · — · شاحن, ناقل · API: list_driver_account_candidates)
• lg driver-advances cancel — Cancel (void) a recorded driver money movement that did not really happen or was entered with the wrong amount. (كتابة · تأكيد + غير قابل للتراجع · شاحن, ناقل · API: cancel_driver_advance)
• lg driver-advances create — Record a money movement between the company and a driver: an advance handed to the driver, money the driver gave back, a closing payout, or a carry-forward opening balance. (كتابة · تأكيد · شاحن, ناقل · API: create_driver_advance) [يأخذ ملفًا: attachment_uuid]
• lg driver-advances delete — Delete a driver money movement that was entered by mistake (duplicate, wrong driver). (كتابة · تأكيد + غير قابل للتراجع · شاحن, ناقل · API: delete_driver_advance)
• lg driver-advances list — List the money movements between the company and its drivers: cash advances handed out, money paid back by the driver, closing payouts and carry-forward opening balances. (قراءة · — · شاحن, ناقل · API: list_driver_advances)
• lg driver-advances update — Correct the non-money details of a recorded driver money movement: its reference, note, or the load it belongs to. (كتابة · تأكيد · شاحن, ناقل · API: update_driver_advance)
• lg driver-availabilities create — Record that a driver is unavailable on some days — "Ali is on leave 14-20 November", "Mehmet rests at home next week", "Kemal is sick from today". (كتابة · تأكيد · ناقل · API: create_driver_availability)
• lg driver-availabilities delete — Delete ONE availability period (id from list_driver_availabilities) — the driver counts as available again on those days. (كتابة · تأكيد + غير قابل للتراجع · ناقل · API: delete_driver_availability)
• lg driver-availabilities list — List drivers' leave, home-rest, sick and other unavailability periods (newest planning input), optionally for one driver and/or a date window. (قراءة · — · ناقل · API: list_driver_availabilities)
• lg driver-availabilities update — Correct one availability period (id from list_driver_availabilities): kind, dates, Schengen presence or note. (كتابة · تأكيد · ناقل · API: update_driver_availability)
• lg driver-expense-settings get — Read this company's driver expense module settings: is the module switched on, which currency receipts and advances are converted into, whether receipts need approval (and above which amount), whether drivers may… (قراءة · — · شاحن, ناقل · API: get_driver_expense_settings)
• lg driver-expense-settings update — Change this company's driver expense module settings — only the fields you pass change. (كتابة · تأكيد · شاحن, ناقل · API: update_driver_expense_settings) [مفتاح manager]
• lg driver-expenses create — File one or MANY expense receipts the user attached to this conversation (fuel, toll, ferry, parking, repair, meal…) into the driver expense ledger as pending expenses of ONE of this company's drivers. (كتابة · تأكيد + غير قابل للتراجع · شاحن, ناقل · API: process_receipt) [يأخذ ملفًا: attachment_uuid, attachment_uuids]
• lg driver-expenses declare — Record a driver expense WITHOUT a receipt (fişsiz şoför harcaması) — "Mehmet dün 40 EUR otopark ödedi, fişi yok", "log 120 PLN toll for driver X". (كتابة · تأكيد · شاحن, ناقل · API: create_driver_expense)
• lg driver-expenses delete — Delete a driver expense entered by mistake (duplicate receipt, wrong driver, test entry). (كتابة · تأكيد + غير قابل للتراجع · شاحن, ناقل · API: delete_driver_expense)
• lg driver-expenses download — Get the download link of a receipt pack that generate_driver_receipt_pack prepared in the background. (قراءة · — · شاحن, ناقل · API: download_driver_receipt_pack)
• lg driver-expenses generate — Produce ONE PDF that contains the driver receipts of a selection — for a trip, a load, a driver statement or a date window — e.g. to hand to accounting or the customer. (قراءة · — · شاحن, ناقل · API: generate_driver_receipt_pack)
• lg driver-expenses get — Read one driver expense (receipt) by its id: merchant, amount, currency, converted amount, category, payment channel, whether it is charged to the driver, and the approval status. (قراءة · — · شاحن, ناقل · API: get_driver_expense)
• lg driver-expenses list — List driver expense receipts (fuel, toll, ferry, parking, food, repair…) with a converted total. (قراءة · — · شاحن, ناقل · API: list_driver_expenses)
• lg driver-expenses list-loads — For ONE driver: which loads they carried and, per load, how many receipts there are, how many still await approval, how much is reimbursable to the driver, how much is company-billed (fuel card / DKV / UTA — never the… (قراءة · — · شاحن, ناقل · API: list_driver_expense_loads)
• lg driver-expenses list-trips — For ONE driver: which trips (load groups) they drove and, per trip, the number of loads and the driver's OWN receipt figures (count, awaiting approval, reimbursable, company-billed fuel-card / DKV / UTA, still… (قراءة · — · شاحن, ناقل · API: list_driver_expense_trips)
• lg driver-expenses review — Approve or reject ONE driver expense (receipt) from the chat, or send an already-decided one back to pending. status=approved means the company accepts the expense (an approved reimbursable receipt can then be counted… (كتابة · تأكيد · شاحن, ناقل · API: review_driver_expense)
• lg driver-expenses set-in-account — Count driver receipts INTO the driver's account (include=true, default) or take them OUT of it (include=false). (كتابة · تأكيد · شاحن, ناقل · API: set_driver_expenses_in_account)
• lg driver-expenses update — Correct a recorded driver expense (receipt or no-receipt): amount, currency, date, category, how it was paid, merchant, description or the load it belongs to — "the parking was 45 EUR not 40", "that fuel was paid with… (كتابة · تأكيد · شاحن, ناقل · API: update_driver_expense)
• lg driver-expenses update-conversion — Retry the currency conversion of ONE driver receipt whose exchange rate could not be resolved (it then sits outside every total and cannot go into a driver statement). (كتابة · — · شاحن, ناقل · API: retry_driver_expense_conversion)
• lg driver-schedules accept — Apply ONE schedule suggestion (suggestion_id from get_driver_schedule): the proposed driver is assigned to the load (or every consignment of the trip — consignments still held by another driver are taken over, and the… (كتابة · تأكيد · ناقل · API: apply_driver_schedule_suggestion)
• lg driver-schedules generate — Compute schedule suggestions for a 7-90 day window starting within 30 days: which driver should take each unassigned load, trip and route plan so that nobody runs out of Schengen days, leave is respected and vehicles do… (كتابة · تأكيد · ناقل · API: generate_driver_schedule)
• lg driver-schedules get — Read one schedule run (schedule_id from generate_driver_schedule / list_driver_schedules): summary (jobs covered, unassignable jobs and why, vehicle idle days before → after, lowest Schengen margin), the suggestions in… (قراءة · — · ناقل · API: get_driver_schedule)
• lg driver-schedules list — List the company's schedule-suggestion runs, newest first: id (schedule_id), status (queued | running | completed | failed), the planned window, objective and whether the run is out of date (is_stale — planning inputs… (قراءة · — · ناقل · API: list_driver_schedules)
• lg driver-schedules reject — Dismiss ONE open schedule suggestion (suggestion_id from get_driver_schedule) so it is no longer offered; nothing is assigned or changed elsewhere. (كتابة · — · ناقل · API: dismiss_driver_schedule_suggestion)
• lg driver-statements cancel — Cancel a statement that should not exist (opened by mistake, duplicated). (كتابة · تأكيد + غير قابل للتراجع · شاحن, ناقل · API: cancel_driver_account)
• lg driver-statements create — Open a NEW draft settlement statement for a driver. (كتابة · تأكيد · شاحن, ناقل · API: create_driver_account)
• lg driver-statements download — Give a short-lived download link to the PDF statement of a FINALISED driver settlement statement — the document the driver sees and signs, with every line, the fuel-card block that is outside the driver maths, and the… (قراءة · — · شاحن, ناقل · API: download_driver_account_pdf)
• lg driver-statements finalize — FINALISE a draft settlement statement — it freezes the document, makes it visible to the driver and (for settle_cash) writes the counter-entry into the advance ledger. (كتابة · تأكيد + غير قابل للتراجع · شاحن, ناقل · API: finalize_driver_account) [مفتاح manager]
• lg driver-statements get — Read one driver settlement statement in full: its status and revision, the driver, the currency, every total (expenses, advances, repayments, receiptless declarations), the NET balance with the sentence that says which… (قراءة · — · شاحن, ناقل · API: get_driver_account)
• lg driver-statements list — List the driver settlement statements (mutabakat belgesi) of this company: code, which driver, status (draft / finalized / cancelled), currency, the net balance and what it means, how many expense and advance lines it… (قراءة · — · شاحن, ناقل · API: list_driver_accounts)
• lg driver-statements reopen — Reopen a FINALISED statement so it can be corrected (a late receipt arrived, a line was wrong). (كتابة · تأكيد · شاحن, ناقل · API: reopen_driver_account) [مفتاح manager]
• lg driver-statements update — Change the note printed on a DRAFT driver settlement statement (e.g. "September trips, fuel excluded"). (كتابة · تأكيد · شاحن, ناقل · API: update_driver_account)
• lg driver-statements update-lines — Attach receipts/advances to a DRAFT statement, or detach ones that should not be on it. (كتابة · تأكيد · شاحن, ناقل · API: update_driver_account_lines)
• lg driver-statuses list — Fleet command centre — every driver's live operational status in one list: last position and its AGE, signal health (streaming / delayed / stale / no_signal / permission_denied / app_missing), duty (on_trip / assigned /… (قراءة · — · شاحن, ناقل · API: list_fleet_driver_statuses)
• lg drivers add-document — Record a driver paper — visa, passport, residence permit, driving licence, SRC certificate, psychotechnic certificate, travel health insurance — for ONE of this carrier's drivers, so its expiry is tracked. (كتابة · تأكيد · ناقل · API: add_driver_document) [يأخذ ملفًا: attachment_uuid]
• lg drivers archive — Archive (deactivate) a driver: their account is disabled, open mobile sessions are revoked and the login link stops working. (كتابة · تأكيد + غير قابل للتراجع · ناقل · API: archive_driver)
• lg drivers calculate — Check whether ONE driver can take a job: Schengen 90/180 days left at the end of the trip (expected and worst case, counting the drive back out and the driver's later planned work), leave / home-rest / sick periods,… (قراءة · — · ناقل · API: check_driver_for_trip)
• lg drivers create — Create a new driver account for this carrier company. (كتابة · تأكيد · ناقل · API: create_driver)
• lg drivers delete-document — Remove a driver paper from the driver's file. (كتابة · تأكيد + غير قابل للتراجع · ناقل · API: delete_driver_document)
• lg drivers get — Full detail of ONE driver of this carrier: identity, archive state, mobile app state, last GPS position, assigned load codes, ALL driver documents (passport, visa, licence, SRC… with expiry and days_to_expiry) and the… (قراءة · — · ناقل · API: get_driver)
• lg drivers list — List this carrier company's drivers with their status, current country, expiring/expired document counts, assigned load codes and vehicle plates. (قراءة · — · ناقل · API: list_drivers)
• lg drivers list-candidates — Rank the company's drivers for a job — which drivers are available and can do it (Schengen days at trip end incl. the drive back, leave/home-rest, other jobs, estimated driving/rest readiness, distance to the start)… (قراءة · — · ناقل · API: list_trip_driver_candidates)
• lg drivers list-documents — List ONE driver's documents (passport, visa, residence permit, licence, SRC, ADR, health insurance…) with document number, issuing country, valid_until, days_to_expiry, is_expired and AI extraction status. (قراءة · — · ناقل · API: list_driver_documents)
• lg drivers list-locations — A driver's GPS trail — the raw position pings from the driver app in a time window, oldest to newest, with the first and last timestamps and the point count. (قراءة · — · ناقل · API: list_driver_locations)
• lg drivers login-link — Produce the driver's 48-hour mobile app login link (sensitive credential). (كتابة · تأكيد · ناقل · API: get_driver_login_link)
• lg drivers request-location — Ask a driver's phone for a fresh position ("where is Ahmet right now — ping him"). (كتابة · — · ناقل · API: request_driver_location)
• lg drivers search — Resolve one of this company's drivers by name to its driver_id. (قراءة · — · ناقل · API: lookup_driver)
• lg drivers update — Correct a driver's first/last name. (كتابة · تأكيد · ناقل · API: update_driver)
• lg drivers update-document — Correct a driver paper already on file — most often its expiry date (valid_until) after a renewal, but also the document number, the issuing country, the type or the note. (كتابة · تأكيد · ناقل · API: update_driver_document)
• lg drivers update-login-link — Generate a NEW 48-hour mobile login link for a driver and kill the old one (lost phone, expired or leaked link). (كتابة · تأكيد + غير قابل للتراجع · ناقل · API: refresh_driver_login_link)
• lg equipment-damages create — Open a damage record on one of the company's own vehicles or trailers (dorse hasar kaydı aç) — "33ABC12 dorsesinin sol arka kapısında ezik var", "record a scratch on the rear bumper of the truck". (كتابة · تأكيد · الكل · API: create_equipment_damage)
• lg equipment-damages delete — Delete a damage record that was opened by mistake (a duplicate, the wrong vehicle). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_equipment_damage)
• lg equipment-damages generate — Produce the equipment damage ledger as an Excel file (the same file as the panel's export button) and return a short-lived download link — e.g. "give me this year's open trailer damages as Excel". (قراءة · — · الكل · API: export_equipment_damages)
• lg equipment-damages list — List the equipment/trailer damages recorded for this company: which vehicle, where on it (area and angle), damage type and severity, whether it is still open or repaired, the estimated and actual repair cost, who is… (قراءة · — · الكل · API: list_equipment_damages)
• lg equipment-damages update — Update an existing damage record: mark it repaired (with repair date, cost and note), dismissed or disputed, change severity/type/area/description, set the estimated cost, or set/clear the responsible driver. (كتابة · تأكيد · الكل · API: update_equipment_damage)
• lg equipment-inspection-links create — Create a one-time link so a driver or agent who is NOT on the platform (port agent, another company's driver) can upload the hand-over photos of one of the company's trailers/vehicles from a phone, without an account. (كتابة · تأكيد · الكل · API: create_equipment_inspection_link)
• lg equipment-inspections create — Record an equipment hand-over inspection of one of the company's own trailers or vehicles on behalf of a driver or the office — "record the pickup inspection of trailer 34ABC12 with these 4 photos, driver Ali".… (كتابة · تأكيد · الكل · API: create_equipment_inspection) [يأخذ ملفًا: photos[].attachment_uuid]
• lg equipment-inspections delete — Delete an equipment inspection that was recorded by mistake (wrong vehicle, duplicate), together with its photos. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_equipment_inspection)
• lg equipment-inspections get — Full detail of ONE equipment hand-over inspection: vehicle, event (pickup / dropoff / interim), who did it and where and when, the AI analysis status with its overall condition and summary, the damages that inspection… (قراءة · — · الكل · API: get_equipment_inspection)
• lg equipment-inspections list — List the equipment hand-over inspections (teslim-tesellüm controls) of this company: which vehicle, the event type (hand-over, take-over, interim), when and where it happened, who performed it (driver or office user, or… (قراءة · — · الكل · API: list_equipment_inspections)
• lg equipment-inspections run — Run the AI damage analysis again on the photos of one equipment inspection (for example after the analysis failed, or photos were added later). (كتابة · تأكيد · الكل · API: reanalyze_equipment_inspection)
• lg equipment-settings get — Read the company's equipment inspection settings: whether the module is on, at which hand-overs an inspection is required (pickup / dropoff), whether photos are required, the minimum photo count, which angles are… (قراءة · — · الكل · API: get_equipment_settings)
• lg equipment-settings update — Change the company's equipment inspection settings — e.g. "turn on equipment inspection and require at least 4 photos with front, rear, left and right at pickup". (كتابة · تأكيد · الكل · API: update_equipment_settings) [مفتاح manager]
• lg equipment-timelines get — Who has one trailer/vehicle right now (custody: in custody of a driver since the last pickup, or released at the last dropoff), the inspections it went through (newest first) and its OPEN damages — in one read. (قراءة · — · الكل · API: get_equipment_timeline)
• lg export-documents add-item — Append a line item to an export document. (كتابة · — · الكل · API: add_export_document_item)
• lg export-documents create — Create a new export document draft. (كتابة · — · الكل · API: create_export_document_draft)
• lg export-documents create-set — Create SEVERAL export document drafts (a set, e.g. commercial invoice + packing list) from ONE source in one go: the source is read once by AI and every chosen document is filled from it. (كتابة · — · الكل · API: create_export_document_set) [يأخذ ملفًا: attachment_uuid]
• lg export-documents delete — Delete one export document of this company (draft or generated). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_export_document)
• lg export-documents duplicate — Copy an existing export document into a NEW draft of the same type (same parties, items and terms; no document number, not generated). (كتابة · — · الكل · API: duplicate_export_document)
• lg export-documents extract — Read a pasted order e-mail, offer or confirmation — or an Excel/CSV/TXT item list given as attachment_uuid — and fill an export document from it. (كتابة · — · الكل · API: extract_export_document_from_text) [يأخذ ملفًا: attachment_uuid]
• lg export-documents generate — Produce the final PDF of an export document AND return a short-lived signed download link for it, so the user gets the file straight from the chat. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: generate_export_document)
• lg export-documents generate-set — Generate several export documents as PDFs in one go and return a short-lived download link for each generated one. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: generate_export_document_set)
• lg export-documents get — Read one export document in full: every filled field as dot-paths, the line items with their 1-based positions, the server-computed totals and which required fields are still empty. (قراءة · — · الكل · API: get_export_document)
• lg export-documents list — List the export documents of the current company (proforma invoice, commercial invoice, packing list, shipping instruction, delivery note, certificate/movement applications, exporter declaration, insurance request). (قراءة · — · الكل · API: list_export_documents)
• lg export-documents options — List the export document types and the ready-made document sets with their credit cost. (قراءة · — · الكل · API: get_export_document_options)
• lg export-documents preview — Before generating several export documents as PDFs, show what it would cost: which documents would spend a credit, which are free (already generated), the total, the remaining balance and the required fields still empty… (قراءة · — · الكل · API: plan_export_document_generation)
• lg export-documents remove-item — Delete one line item by its 1-based position. (كتابة · — · الكل · API: remove_export_document_item)
• lg export-documents set — Set one or more fields on an export document draft. (كتابة · — · الكل · API: set_export_document_fields)
• lg export-documents update-item — Change columns of one existing line item, addressed by its 1-based position from get_export_document. (كتابة · — · الكل · API: update_export_document_item)
• lg finance calculate — Build a budget / financial forecast (bütçe tahmini, gelecek yıl bütçesi, nakit/ciro projeksiyonu) from the company's MEASURED history, month by month. (قراءة · — · الكل · API: generate_budget_forecast)
• lg finance get — One call that returns the measured financial BASE for a period — the numbers a budget, a forecast, a business plan, a cash-flow projection or a board summary is built on, instead of chaining six separate reads. (قراءة · — · الكل · API: get_financial_snapshot)
• lg fleet-documents list — List fleet documents that expire soon (or already expired): vehicle papers (insurance, inspection, permits) and — for carriers — driver papers (passport, visa, licence, SRC). (قراءة · — · شاحن, ناقل · API: list_expiring_documents)
• lg freight-invoices archive — Archive (remove from the active list) a freight invoice YOUR company uploaded — e.g. a duplicate or the wrong file. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: archive_freight_invoice)
• lg freight-invoices create — Attach 1-20 freight invoices (navlun faturası) to a load. (كتابة · تأكيد · الكل · API: upload_freight_invoices) [يأخذ ملفًا: attachment_uuids]
• lg freight-invoices list — List the freight invoices (navlun faturaları) of a load that your company is a party to: who uploaded it, amount and currency, invoice date, the AI reading status, and which load parties it is shared with. (قراءة · — · الكل · API: list_freight_invoices)
• lg freight-invoices set-visibility — Choose which load parties can see a freight invoice YOUR company uploaded — e.g. "share the invoice with the receiver too", "only we should see it". (كتابة · تأكيد · الكل · API: set_freight_invoice_visibility)
• lg freight-reports get — Freight (navlun) cost report over the loads this company can see: agreed freight totals per currency plus the EUR equivalent, freight-invoice totals, how many loads have NO freight recorded (listed by code), a breakdown… (قراءة · — · شاحن, ناقل · API: get_freight_cost_report)
• lg fuel-cards create — Register a fuel card (DKV, UTA and the like) in the fleet card book, optionally tied to a driver or a vehicle. (كتابة · تأكيد · شاحن, ناقل · API: create_fuel_card)
• lg fuel-cards delete — Delete a fuel / toll card (DKV, UTA, Shell…) that was entered BY MISTAKE. (كتابة · تأكيد + غير قابل للتراجع · شاحن, ناقل · API: delete_fuel_card)
• lg fuel-cards list — List the company's fuel and toll cards (DKV, UTA, Eurowag, E100, Shell, OMV, Aral, Petrol Ofisi, Opet…) with the last four digits, the driver or vehicle they are tied to, and whether they are active. (قراءة · — · شاحن, ناقل · API: list_fuel_cards)
• lg fuel-cards update — Update a fuel card: move it to another driver or vehicle, change its label or note, or DEACTIVATE it (is_active false) when the card is cancelled. (كتابة · تأكيد · شاحن, ناقل · API: update_fuel_card)
• lg handoff-links generate — Get the logistivo.com link for work that deliberately stays in the browser: package_purchase (buy or upgrade a package; optional package_slug from list_packages and billing_period monthly|yearly pre-select it — the… (قراءة · — · الكل · API: get_browser_handoff_link)
• lg import-duties get — Read the Turkish import duty table for one GTİP code: customs duty (İthalat Rejimi Kararı) and additional customs duty / İGV, with every country-group column, plus the statutory duty from the nomenclature. (قراءة · — · الكل · API: get_import_duty_rates)
• lg integration-keys list — List the company's integration (API) keys: name, uuid, which teammate it acts as, scope (read/write) and allowed domains, access level (manager/employee), environment (live/sandbox), status (active/revoked/expired),… (قراءة · — · الكل · API: list_integration_keys) [مفتاح manager]
• lg integration-keys revoke — Revoke one of the company's integration (API) keys by its uuid from list_integration_keys: the key stops working immediately and cannot be re-enabled (issue a new key instead). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: revoke_integration_key) [مفتاح manager]
• lg invitations create — Invite colleagues to this company by e-mail — one address in email, or up to 20 at once in emails (all-or-nothing: the seat limit and every address's domain are checked before anything is sent). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: invite_teammate) [مفتاح manager]
• lg invitations list — List teammate invitations of this company that are not completed yet (pending / e-mail verified / account created), with invitation_code, e-mail, role and expiry. (قراءة · — · الكل · API: list_pending_invitations)
• lg invitations resend — Re-send a pending teammate invitation e-mail and extend its expiry by 14 days. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: resend_invitation) [مفتاح manager]
• lg invitations revoke — Cancel a pending teammate invitation so its link stops working (it can later be re-sent). (كتابة · تأكيد · الكل · API: revoke_invitation) [مفتاح manager]
• lg invoice-settings get — Read the invoice document settings (fatura ayarları, fatura şablonu ayarları): which invoice templates exist, which template configuration is the company default, which fields of it are filled (logo, seller address,… (قراءة · — · الكل · API: get_invoice_settings)
• lg invoice-templates create — Create a new invoice template configuration for your company: a base template plus field values (colours, font, header / footer text, IBANs shown, QR code, language; logo and signature from uploaded images). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: create_invoice_template) [مفتاح manager] [يأخذ ملفًا: logo_attachment_uuid, signature_image_attachment_uuid]
• lg invoice-templates delete — Delete one of your invoice template configurations. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_invoice_template) [مفتاح manager]
• lg invoice-templates get — Show the fillable fields of an invoice template (logo, colours, font, header / footer text, IBANs shown, QR code, signature, language) with their types, options and defaults — and, for one of your configurations, its… (قراءة · — · الكل · API: get_invoice_template)
• lg invoice-templates set-default — Make one of your invoice template configurations the company default; the previous default stops being default. (كتابة · تأكيد · الكل · API: set_default_invoice_template) [مفتاح manager]
• lg invoice-templates update — Edit one of your invoice template configurations: switch its base template, rename it, change field values (merged over the stored ones — only the keys you pass change), replace the logo / signature image, or make it… (كتابة · تأكيد + غير قابل للتراجع · الكل · API: update_invoice_template) [مفتاح manager] [يأخذ ملفًا: logo_attachment_uuid, signature_image_attachment_uuid]
• lg invoices add-line — Add a line item to a DRAFT invoice and recompute totals (tax auto-resolved if tax_rate_id omitted). (كتابة · — · الكل · API: add_invoice_line)
• lg invoices add-payment — Record money received (sales invoice) or paid (purchase invoice) against ONE issued invoice: writes the payment, posts the balanced journal entry and reduces the remaining balance. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: record_invoice_payment)
• lg invoices cancel — Cancel an ISSUED invoice this company issued: posts the reversing journal entry and marks the invoice cancelled. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: cancel_invoice)
• lg invoices create — Create a DRAFT invoice (reversible) issued by the current company to a recipient business contact. (كتابة · — · الكل · API: create_invoice_draft)
• lg invoices delete-draft — Delete a DRAFT invoice of this company together with its lines and taxes. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_invoice_draft)
• lg invoices download — Get a short-lived download link for the PDF of an invoice visible to this company (and the e-invoice XML when one exists). (قراءة · — · الكل · API: download_invoice_pdf)
• lg invoices get — Read one invoice in full: parties, load link, dates, every line with tax, tax breakdown, totals, remaining balance and the payments recorded against it. (قراءة · — · الكل · API: get_invoice)
• lg invoices issue — Issue (finalize) a DRAFT invoice: assigns a number and posts accounting entries. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: issue_invoice)
• lg invoices list — List invoices visible to this company — the ones it issued and the ones issued to it (as a linked party). (قراءة · — · الكل · API: list_invoices)
• lg invoices preview — Show the user a full preview of a DRAFT invoice (recipient, line items, tax breakdown, totals) WITHOUT issuing it. (قراءة · — · الكل · API: preview_invoice · مُهمَل: 2026-09-03 · استخدم get_invoice)
• lg invoices remove-line — Remove one line from a DRAFT invoice your company issued; the totals are recalculated. (كتابة · تأكيد · الكل · API: remove_invoice_line)
• lg invoices reverse-payment — Undo ONE payment/collection recorded on an invoice: posts the reversing journal entry, gives the amount back to the invoice's remaining balance and removes the payment row. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: reverse_invoice_payment)
• lg invoices update — Edit the header of a DRAFT invoice your company issued: recipient contact, currency, issue / due date, the printed note and the invoice template. (كتابة · — · الكل · API: update_invoice_draft)
• lg invoices update-line — Edit one line of a DRAFT invoice your company issued (text, quantity, unit, net unit price, discount, tax rate, order). (كتابة · — · الكل · API: update_invoice_line)
• lg join-requests approve — Approve a pending join request: the applicant becomes a user of our company with the EMPLOYEE role, takes one team seat and is e-mailed the decision. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: approve_join_request) [مفتاح manager]
• lg join-requests list — List PENDING requests from people asking to join our company (they signed up with an e-mail on one of our verified domains and picked our company). (قراءة · — · الكل · API: list_join_requests) [مفتاح manager]
• lg join-requests reject — Reject a pending join request: the applicant does not join our company and is e-mailed the decision. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: reject_join_request) [مفتاح manager]
• lg journal-entries create — Post a manual double-entry journal entry (yevmiye fişi). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: create_journal_entry)
• lg journal-entries get — Read one journal entry with its lines (account code/name, debit, credit, counterparty) and totals. (قراءة · — · الكل · API: get_journal_entry)
• lg journal-entries list — List journal entries (yevmiye fişleri) of the company, newest first, with optional date window. (قراءة · — · الكل · API: list_journal_entries)
• lg language-settings get — Read the signed-in user's own language settings (dil ayarları). (قراءة · — · الكل · API: get_language_settings)
• lg language-settings update — Change the signed-in user's OWN language settings — "dilimi İngilizce yap", "e-postalarım Türkçe gelsin", "sohbet mesajlarını Almancaya çevir". (كتابة · — · الكل · API: set_language)
• lg load-ai-settings get — Read our company's load AI reminder setting (Settings → Loads): whether the assistant posts reminders into load chats about loads whose status was not updated (ai_warning_enabled) and on which days (warning_frequency:… (قراءة · — · الكل · API: get_load_ai_settings)
• lg load-ai-settings update — Change our company's load AI reminders (Settings → Loads): ai_warning_enabled turns the reminders the assistant posts into load chats on or off; warning_frequency picks the days (daily, mon_wed_fri, weekly_wed,… (كتابة · تأكيد · الكل · API: update_load_ai_settings) [مفتاح manager]
• lg load-containers create — Add a sea container number to a load (yüke konteyner ekle) — "add MSC container MSCU1234565 to FKZ8515". (كتابة · تأكيد · شاحن, ناقل · API: add_load_container)
• lg load-containers delete — Delete a container record from a load (konteyneri sil) — only while its vessel tracking has NOT started (otherwise refused with INVALID_STATUS). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_load_container)
• lg load-containers get — Show one container of a load and the last known position of the ship carrying it (konteyner konumu): ship name/IMO, latitude/longitude, speed, course, destination, ETA and the position time. (قراءة · — · الكل · API: get_load_container)
• lg load-containers list — List the sea containers recorded on a load (konteynerler) with their shipping line, whether vessel tracking has started and which ship carries them. (قراءة · — · الكل · API: list_load_containers)
• lg load-containers set-tracking — Start vessel tracking for a load from its containers (konteyner takibini başlat): the shipping line is queried for each container until the vessel carrying it is found; that ship is then tracked on the load's map and… (كتابة · تأكيد · الكل · API: start_load_container_tracking)
• lg load-documents create — File one or MANY documents the user attached to this conversation onto a load: each file is stored as a company document and posted into the load's chat, where every participant (customer, carrier, customs broker) sees… (كتابة · تأكيد + غير قابل للتراجع · الكل · API: attach_chat_file_to_load) [يأخذ ملفًا: attachment_uuid, attachment_uuids]
• lg load-documents list — List the documents (CMR, invoice, packing list, customs papers, photos…) filed on a load — i.e. the files shared in that load's chat. (قراءة · — · الكل · API: list_load_documents)
• lg load-groups add-loads — Merge EXISTING loads into a groupage trip you own as consignments (they keep their own code, chat, documents and participants; only the trip membership changes — nothing is duplicated and NO credit is used). (كتابة · تأكيد · شاحن, ناقل · API: add_loads_to_group)
• lg load-groups create — Create a groupage trip (parsiyel/sefer): ONE truck carrying several ISOLATED consignments; each consignment is its own load with its own chat/documents/status and receivers never see each other. (كتابة · تأكيد + غير قابل للتراجع · شاحن, ناقل · API: create_load_group)
• lg load-groups download — Download the route report of a groupage trip (sefer / parsiyel, code like LGV00253): route_pdf = detailed route report with map and itinerary, route_xlsx = the same as Excel, driver_sheet_pdf = the simplified driver… (كتابة · — · شاحن, ناقل · API: download_load_group_report)
• lg load-groups get — Detail of one groupage trip: consignments visible to you (load code, status, receiver, route, driver), planned date, optimised master route summary and stop count. (قراءة · — · شاحن, ناقل · API: get_load_group)
• lg load-groups list — List groupage trips (parsiyel / sefer: one truck, several isolated consignment loads) this company owns or — for carriers — carries, newest first, with visible consignment count and route optimisation state. (قراءة · — · شاحن, ناقل · API: list_load_groups)
• lg load-groups optimize — Re-optimise the master route of a groupage trip you own and RETURN the new itinerary: the ordered stops (pickup → export customs → import customs → dropoff), each stop's address and consignment codes, the total distance… (كتابة · — · شاحن, ناقل · API: optimize_trip_route)
• lg load-groups remove-load — Take one consignment out of a groupage trip you own. (كتابة · تأكيد · شاحن, ناقل · API: remove_load_from_group)
• lg load-heatmaps generate — Produce the load heatmap report (PDF, with QR code and the list of your active loads: code, departure, arrival, date, weight), save it to the company's reports and return a download link. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: generate_load_heatmap_report)
• lg load-heatmaps get — Load heatmap data in words: the densest departure and arrival areas of your active loads, ranked by number of loads and by total kilograms. (قراءة · — · الكل · API: get_load_heatmap)
• lg load-locations create — Report a position for a load on behalf of the carrier (konum bildir) — "FKZ8515 is at Kapıkule now", "the truck is at 41.0, 28.9". (كتابة · تأكيد + غير قابل للتراجع · ناقل · API: report_load_location)
• lg load-locations list — Show a load's position history (konum geçmişi) and its last known position — "where is FKZ8515 now", "where was it yesterday", "show the truck's track". (قراءة · — · الكل · API: list_load_locations)
• lg load-locations list-routes — Show the road route segments drawn on a load's tracking map (rota parçaları), each with distance (metres) and duration (seconds): from the pickup address to the first reported position, between reported positions, and… (قراءة · — · الكل · API: list_load_route_segments)
• lg load-notifications list-recipients — Show which load parties can receive a load notification (departure, arrival, daily location) and how many of their people are subscribed per channel (e-mail, push, SMS). (قراءة · — · الكل · API: list_load_notification_recipients)
• lg load-notifications send — Send a departure / arrival / daily-location notification about a load to chosen load parties — e.g. "notify the receiver that FRT6470 arrived". (كتابة · تأكيد + غير قابل للتراجع · الكل · API: send_load_notification)
• lg load-notifications send-email — E-mail a departure / arrival / location update about a load to people you choose from YOUR OWN company directory (business contact persons) — e.g. "e-mail Mehmet at Arkas the location of FKZ8515". (كتابة · تأكيد + غير قابل للتراجع · الكل · API: send_load_email_notification)
• lg load-participants create — Add a party to a load (yüke taraf ekle) — "FKZ8515'e Arkas'ı alıcı olarak ekle" — or assign a sub-carrier. business_contact_id comes from lookup_business_contact (your own directory). (كتابة · تأكيد · الكل · API: add_load_participant)
• lg load-participants delete — Remove a party or a sub-carrier from a load (yükten taraf çıkar) — "FKZ8515'ten alt taşıyıcı Yılmaz Nakliyat'ı kaldır". participant_id comes from list_load_participants. (كتابة · تأكيد · الكل · API: remove_load_participant)
• lg load-participants list — List a load's parties (yük tarafları): sender, receiver, carrier and sub-carriers, organizer, sender/receiver customs brokers — with participant_id (needed by every other load-participant command), position (0 = primary… (قراءة · — · الكل · API: list_load_participants)
• lg load-participants set-order — Put the parties of one role in a new order (load owner only); the first id becomes the primary. participant_ids must list ALL current rows of that role (from list_load_participants). (كتابة · تأكيد · الكل · API: reorder_load_participants)
• lg load-participants set-primary — Make a party the primary one in its role (load owner only) — e.g. the main receiver or main customs broker. participant_id from list_load_participants. (كتابة · تأكيد · الكل · API: set_primary_load_participant)
• lg load-participants update — Change one load party's settings (load owner only) — "Arkas FKZ8515'i görmesin": share_with_assigned_company (can the linked company see the load; cannot be turned off for a sub-carrier), conversation_user_ids (only… (كتابة · تأكيد · الكل · API: update_load_participant)
• lg load-party-suggestions approve — Accept a party suggestion: link the suggested business contact to your OWN load as sender or receiver (business_contact_id and party_role from list_load_party_suggestions). (كتابة · تأكيد · الكل · API: confirm_load_party_suggestion)
• lg load-party-suggestions list — Show sender/receiver suggestions for one of your OWN loads: parties named in the load's documents that match a contact in your directory but are not linked to the load yet. (قراءة · — · الكل · API: list_load_party_suggestions)
• lg load-party-suggestions reject — Close wrong party suggestions on your OWN load so they are not suggested again — "bu önerileri bir daha gösterme". (كتابة · — · الكل · API: dismiss_load_party_suggestions)
• lg load-reports get — Build a report of your ACTIVE loads, optionally filtered by sender, receiver, transport mode, departure country or arrival country. format=summary (default) answers in chat: the number of loads and how many are in each… (قراءة · — · الكل · API: get_load_report)
• lg load-reports options — List the companies you can filter the load report by — the senders, receivers, carriers and other parties that appear on your active loads — with their company id and role. (قراءة · — · الكل · API: get_load_report_options)
• lg load-types search — Resolve a load/transport type (e.g. (قراءة · — · الكل · API: lookup_load_type)
• lg load-vehicles delete — Detach the fleet equipment from a load: both slots by default, or only the tractor unit / only the trailer. (كتابة · تأكيد · الكل · API: clear_load_equipment)
• lg load-vehicles get — Show which tractor unit (or truck/van) and which trailer are attached to a load, whether they belong to your own fleet, and whether the load can still be changed. (قراءة · — · الكل · API: get_load_equipment)
• lg load-vehicles set — Attach one of your own fleet vehicles to a load: the tractor unit / truck slot (plate) and/or the trailer slot (trailer_plate). (كتابة · تأكيد · الكل · API: assign_vehicle_to_load)
• lg loads add-order-reference — Attach an order reference to a load (sipariş referansı ekle) — "FKZ8515'e satın alma siparişi PO-4471 ekle". order_type is the kind of order (e.g. purchase, sales), order_no the number. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: add_load_order_reference)
• lg loads analyze-documents — Re-run the background AI consistency analysis of a load's documents (does the invoice contradict the CMR, the packing list, the declared weight…) and refresh the load's problem flag with the outcome. (كتابة · — · الكل · API: reanalyze_load_documents)
• lg loads archive — Archive one of the company's OWN loads (yükü arşivle) — "FKZ8515'i arşive al". (كتابة · تأكيد + غير قابل للتراجع · الكل · API: archive_load)
• lg loads assign-driver — Assign one of this company's drivers to a load so the driver sees it in the mobile app and starts reporting position. (كتابة · تأكيد · ناقل · API: assign_driver_to_load)
• lg loads audit-documents — Cross-check the documents already attached to loads and report, PER LOAD, whether their package counts and gross weights agree. (قراءة · — · الكل · API: audit_load_documents)
• lg loads close-problem — Close the open document-consistency flag of ONE load, from the chat. action=resolved means the contradiction was actually fixed (a corrected document was uploaded); action=dismissed means it was a false alarm and should… (كتابة · تأكيد · الكل · API: resolve_load_problem_flag)
• lg loads create — Open a freight load (yük). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: create_load)
• lg loads download — Generate a load's CMR consignment note as a PDF and return a short-lived download link — "FKZ8515'in CMR'ını ver". (قراءة · — · الكل · API: download_load_cmr)
• lg loads extract — Read a booking/order text (an e-mail body, a note, an ERP export line) and return the load fields it contains, in the quick-load form's shape: transport mode, countries, dates, load type, vehicle type, weight, goods… (قراءة · — · شاحن · API: extract_load_from_text)
• lg loads get — Read one load in full by its code: route, dates, weight, current status, parties (sender/receiver/carrier), agreed freight (freight_amount + freight_currency) with its freight invoices (number, date, total), latest… (قراءة · — · الكل · API: get_load)
• lg loads list — List the freight loads (yük) this company can see, newest first. (قراءة · — · الكل · API: list_loads)
• lg loads list-associated — List the loads of the same multi-vehicle order as a given load (aynı siparişin diğer araçları) — every active load that shares its vehicle group code (LG…) and that your company can see, with status, date and carrier. (قراءة · — · الكل · API: list_associated_loads)
• lg loads list-billing-targets — Show who you can invoice for a load: its commercial parties (sender, receiver, carrier) you are allowed to bill, each with recipient_contact_id to pass to create_invoice_draft and in_my_directory (true = already in your… (قراءة · — · الكل · API: list_load_billing_targets)
• lg loads list-problems — List loads whose uploaded documents the AI consistency check found to CONTRADICT each other (e.g. invoice weight vs CMR weight). (قراءة · — · الكل · API: list_load_problem_flags)
• lg loads list-status-history — Show a load's status history (durum geçmişi) in order — when it went pending, in transport, transit, delivered (done). (قراءة · — · الكل · API: list_load_status_history)
• lg loads list-stops — List the stops of a multi-stop load (çok duraklı yük — several pickups/drop-offs on one load) in route order, with type (pickup, dropoff, customs_exit, customs_entry), company, address, leg distance/duration and whether… (قراءة · — · الكل · API: list_load_stops)
• lg loads optimize — Re-order the stops of a multi-stop load for the shortest driving route (pickups first, then drop-offs) and store the new order with leg distances — "optimise FKZ8515's stops". (كتابة · — · الكل · API: optimize_load_stops)
• lg loads options — Read a load's editable fields, their current values and the allowed options (load types, vehicle types, goods classes, stackability, incoterms, movement types) — "FKZ8515'te neyi değiştirebilirim?". (قراءة · — · الكل · API: get_load_edit_form)
• lg loads preview-copy — Prepare a copy draft of one of your company's OWN loads (yükü kopyala) — "FKZ8515'in aynısından bir tane daha açalım": transport mode, countries, addresses, load type, vehicle type, weight, goods class, incoterms, ports… (قراءة · — · الكل · API: get_load_copy_template)
• lg loads remove-driver — Remove the driver from a load (the opposite of assign_driver_to_load): the load disappears from the driver's app and GPS tracking of the load stops. (كتابة · تأكيد · ناقل · API: unassign_driver_from_load)
• lg loads search — Full-text search across your loads (yük ara) — company names, pickup/delivery address, order references, load code, text written in the load chat and text read from documents shared in the chat: "içinde PO-4471 geçen… (قراءة · — · الكل · API: search_loads)
• lg loads set-status — Move a load to a new transport status and append it to the load's status history (this is what the customer sees on the tracking screen). (كتابة · تأكيد + غير قابل للتراجع · ناقل · API: update_load_status)
• lg loads set-stop-status — Mark one stop of a multi-stop load as completed, or undo it (completed=false) — "FKZ8515's second drop-off is done". (كتابة · تأكيد · ناقل · API: mark_load_stop_completed)
• lg loads set-tracking — Turn a load's GPS location tracking on or off (konum takibi) — "stop location tracking for FKZ8515", "resume tracking". (كتابة · تأكيد · ناقل · API: set_load_location_tracking)
• lg loads update — Edit an existing load (yükü düzenle): loading date, weight, load type, vehicle types, goods class, stackability, pickup/delivery address, incoterms, movement type, loading/destination port. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: update_load)
• lg maturity-options list — The selectable payment terms (vade): maturity_option_id and the number of days (0 = cash / peşin). maturity_option_id is what update_company_profile takes. (قراءة · — · الكل · API: list_maturity_options)
• lg notification-settings get — Read our company's notification switches (Settings → Notifications): which e-mail notifications (type "notification") and push notifications (type "web-push") are on for the whole company — e.g. message, load, demand… (قراءة · — · شاحن · API: get_notification_settings) [مفتاح manager]
• lg notification-settings update — Turn our company's notification switches on or off (Settings → Notifications) — e.g. stop load chat push notifications or message e-mails for the whole company. settings is a list of {slug, enabled}; slugs come from… (كتابة · تأكيد · شاحن · API: update_notification_settings) [مفتاح manager]
• lg notifications list — Read the signed-in user's own notification inbox (the bell icon): what happened, which kind of event it was, when, whether it is still unread, and the panel address the notification points at. (قراءة · — · الكل · API: list_notifications)
• lg notifications mark-read — Mark ALL of the signed-in user's unread notifications as read (empty the bell). (كتابة · — · الكل · API: mark_notifications_read)
• lg packages get — Read this company's package and CREDIT balance: how many credits are left, how many the package grants per year, how many were used, the renewal date, and the assistant token usage of the current period (1,000,000… (قراءة · — · الكل · API: get_credit_balance)
• lg packages list — List the Logistivo packages this company can buy: slug, name, monthly price and yearly upfront total in the company's BILLING currency (TRY for Türkiye-billed companies, EUR otherwise — never converted with an exchange… (قراءة · — · الكل · API: list_packages)
• lg pallets add-measurement — Record a NEW measurement for an existing pallet (dimensions in centimetres and/or gross weight in kilograms). (كتابة · تأكيد · الكل · API: add_pallet_measurement)
• lg pallets add-proof — Attach a proof photo to one of this company's pallets (e.g. the wrapped pallet, its label, damage on arrival). (كتابة · — · الكل · API: add_pallet_proof) [يأخذ ملفًا: attachment_uuid]
• lg pallets calculate — Suggest the missing base side of a pallet from a standard footprint (EUR 120×80, industrial 120×100, half 80×60; ±5 cm) when only one base side is known, and compute the volume when length, width and height are all… (قراءة · — · الكل · API: complete_pallet_dimensions)
• lg pallets create — Register a NEW pallet in a warehouse, optionally with its first measurement. warehouse_id is required — resolve the warehouse name with lookup_warehouse first. (كتابة · تأكيد · الكل · API: create_pallet)
• lg pallets delete — Delete one of this company's pallet records. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_pallet)
• lg pallets delete-proof — Remove one proof photo from one of this company's pallets. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_pallet_proof)
• lg pallets extract — Estimate a pallet's content label, dimensions (cm) and gross weight (kg) from photo(s) the user attached to THIS conversation. (كتابة · — · الكل · API: extract_pallet_from_photos) [يأخذ ملفًا: attachment_uuids]
• lg pallets get — Read one pallet in full: its identity (code, label, SKU, barcode), status, warehouse and area, the FULL measurement history (each row with its id, source — manual, lidar, arcore or ai_photo — and confidence), its proof… (قراءة · — · الكل · API: get_pallet)
• lg pallets list — List the pallets of this company: code, label, SKU/barcode, status, which warehouse and area it sits in, its latest measured dimensions (cm) and gross weight, and how many proof photos it has. (قراءة · — · الكل · API: list_pallets)
• lg pallets update — Update an existing pallet: its status (in_stock, in_transit, reserved, shipped, disposed), its label/SKU/barcode/note, or MOVE it to another warehouse or area. (كتابة · تأكيد · الكل · API: update_pallet)
• lg parasut-contacts create — Create a new customer or supplier contact IN PARAŞÜT and keep its local copy. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: create_parasut_contact)
• lg parasut-contacts list — List the customer / supplier contacts held in Paraşüt (the local copy synchronised from Paraşüt): parasut_contact_id (the Paraşüt id used by create_parasut_sales_invoice — NOT a business contact id), name, short name,… (قراءة · — · الكل · API: list_parasut_contacts)
• lg parasut-invoices create — Issue a SALES invoice in Paraşüt for one of this company's Paraşüt contacts, as an e-invoice (scenario commercial or basic — the recipient must be an e-invoice user) or an e-archive invoice (scenario e_archive); check… (كتابة · تأكيد + غير قابل للتراجع · الكل · API: create_parasut_sales_invoice)
• lg parasut-invoices list — List invoices held in Paraşüt (local copy): sales invoices (default) or purchase bills, newest issue date first — invoice id and number, item type, description, issue / due date, net / gross / VAT totals, currency,… (قراءة · — · الكل · API: list_parasut_invoices)
• lg parasut-invoices options — Return the options of the Paraşüt invoice form: income/expense categories (category_id), the Paraşüt bank and cash accounts, and — with tax_number — whether that VKN is a registered e-invoice user (then use scenario… (قراءة · — · الكل · API: get_parasut_invoice_options)
• lg parasut-settings delete — Disconnect Paraşüt from this company: the saved credentials are removed, the accounting provider switches back to local when it was Paraşüt, and the LOCAL copies pulled from Paraşüt (contacts, invoices, bank accounts,… (كتابة · تأكيد + غير قابل للتراجع · الكل · API: disconnect_parasut) [مفتاح manager]
• lg parasut-settings get — Show the Paraşüt integration status of this company: whether it is connected, the Paraşüt firm number, the user name, the client id/secret MASKED (last 4 characters only), when it was connected, the token status and the… (قراءة · — · الكل · API: get_parasut_settings) [مفتاح manager]
• lg parasut-settings update — Connect this company's Paraşüt account or renew its credentials (replaces an existing connection). (كتابة · تأكيد · الكل · API: connect_parasut) [مفتاح manager] [CLI فقط]
• lg payables list — Payables ("whom do we owe how much"): per-supplier totals of recorded purchase invoices — invoiced, paid, remaining, earliest due date — with a per-currency breakdown and an overall summary. (قراءة · — · الكل · API: list_payables)
• lg payment-cards delete — Remove a saved payment card (card_id from list_payment_cards). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: delete_payment_card) [مفتاح manager]
• lg payment-cards list — List the company's saved payment cards, MASKED (last four digits only), with the card holder name, expiry and which one is the default card the monthly subscription is charged to. (قراءة · — · الكل · API: list_payment_cards)
• lg payment-cards set-default — Make one of the saved cards (card_id from list_payment_cards) the DEFAULT card: the monthly package payment is charged to it from now on, and every other card loses the default flag. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: set_default_payment_card) [مفتاح manager]
• lg payment-instructions cancel — CANCEL a pending bank payment instruction: the reservation on its invoices is released so they can be paid another way, and the instruction becomes "cancelled". (كتابة · تأكيد + غير قابل للتراجع · الكل · API: cancel_settlement_instruction)
• lg payment-instructions download — Get the bank payment instruction document (PDF) with a short-lived download link. (قراءة · — · الكل · API: download_settlement_instruction)
• lg payment-instructions get — Read one bank payment instruction: its code, template, effective date, status with timestamps and cancel reason, its note, and — when the PDF has already been rendered — a short-lived signed link to it so the user gets… (قراءة · — · الكل · API: get_settlement_instruction)
• lg payment-instructions list — List the bank payment instructions of this company: instruction code, which template (bank format) it uses, its effective date, status (pending, executed, cancelled) and when it was executed or cancelled. (قراءة · — · الكل · API: list_settlement_instructions)
• lg payment-instructions run — EXECUTE a pending bank payment instruction (banka talimatını yürüt / uygula): the reserved invoices are paid, the payments and journal entries are written with the instruction's effective date, and the instruction… (كتابة · تأكيد + غير قابل للتراجع · الكل · API: execute_settlement_instruction)
• lg planning-boards get — The planning calendar: for every driver, the stretches of days with planned work inside the Schengen area (planned_in), days assumed inside (drive back, assumed_in), planned work outside (planned_out), leave / rest… (قراءة · — · ناقل · API: get_planning_board)
• lg plans archive — Close a plan because the user says the work is finished or abandoned. (كتابة · — · الكل · API: archive_plan)
• lg plans create — Write down a multi-step job so it survives between conversations ("link these 5 loads to a trip, then invoice them"). (كتابة · تأكيد · الكل · API: create_plan)
• lg plans get — Read one plan: the steps that were agreed AND the commands that actually ran while it was active. (قراءة · — · الكل · API: get_plan)
• lg plans list — List this company's plans, newest first. (قراءة · — · الكل · API: list_plans)
• lg ports search — Find a seaport by name or UN/LOCODE (liman ara) — "Mersin", "TRMER", "Trieste". (قراءة · — · الكل · API: lookup_port)
• lg preferences create — Remember a lasting preference of THIS user, so it applies to every future conversation too ("always show amounts in EUR", "write driver names surname first", "I want the weekly summary on Mondays"). (كتابة · — · الكل · API: remember_preference)
• lg preferences delete — Forget one stored preference of this user. (كتابة · — · الكل · API: forget_preference)
• lg preferences list — List what you have been asked to remember about THIS user, with the labels. (قراءة · — · الكل · API: list_preferences)
• lg product-brands create — Create a new product brand for this company (the panel's "new brand"). (كتابة · تأكيد · شاحن · API: create_product_brand)
• lg product-brands list — List this company's product brands (id, name, code, active flag, number of products). (قراءة · — · شاحن · API: list_product_brands)
• lg product-categories create — Create a new product category for this company (the panel's "new category"). (كتابة · تأكيد · شاحن · API: create_product_category)
• lg product-categories list — List this company's product categories (id, name, code, active flag, number of products). (قراءة · — · شاحن · API: list_product_categories)
• lg products add-image — Add a photo to a product's gallery. (كتابة · — · شاحن · API: add_product_image) [يأخذ ملفًا: attachment_uuid]
• lg products create — Define a new product in this company's catalogue so stock can be recorded against it: name plus optionally its unit of measure, SKU, barcode, category, brand, minimum stock level, reorder quantity and lot tracking. (كتابة · تأكيد · شاحن · API: create_product)
• lg products delete — Delete a product from this company's catalogue. (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: delete_product)
• lg products delete-image — Remove one photo from a product's gallery (image_id from get_product). (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: delete_product_image)
• lg products extract — Read product details (name, description, SKU, barcode, unit, category, brand) from 1-5 photos of the product or its label — the panel's "fill from photo" button. (كتابة · — · شاحن · API: extract_product_from_photos) [يأخذ ملفًا: attachment_uuids]
• lg products get — Show one product of this company in full: code, SKU, barcode, unit, category and brand, low-stock threshold and reorder quantity, lot tracking, its photos (with image_id for delete_product_image /… (قراءة · — · شاحن · API: get_product)
• lg products list — List the products of this company: code, name, SKU/barcode, unit, category and brand, whether it is active, and its low-stock threshold. (قراءة · — · شاحن · API: list_products)
• lg products list-low-stock — List the products whose quantity on hand is BELOW their low-stock threshold (strictly below — a product exactly at the threshold is not listed), with the quantity on hand and the threshold itself. (قراءة · — · شاحن · API: list_low_stock_products)
• lg products options — List the units of measure a product can be held in (slug for create_product / update_product unit, with Turkish and English names). (قراءة · — · شاحن · API: get_product_options)
• lg products search — Resolve a product to its product_id + on-hand quantity. (قراءة · — · شاحن · API: lookup_product)
• lg products set-primary-image — Make one of a product's photos its cover image (image_id from get_product). (كتابة · — · شاحن · API: set_product_primary_image)
• lg products update — Correct an existing product: its name, unit, SKU, barcode, category, brand, minimum stock level, reorder quantity, lot tracking, note, or whether it is active. (كتابة · تأكيد · شاحن · API: update_product)
• lg receivables get — Account statement of one contact: every sales invoice issued to them and every collection, in date order with a running balance, plus totals (invoiced, paid, open balance, open invoice count). (قراءة · — · الكل · API: get_receivable_statement)
• lg receivables list — Receivables ("who owes us how much"): per-contact totals of issued sales invoices — invoiced, paid, remaining — with a per-currency breakdown and an overall summary. (قراءة · — · الكل · API: list_receivables)
• lg report-files create — Turn a table you compiled from tool results into a downloadable Excel (default), PDF or CSV file — any custom table, list, comparison or export, with optional charts. (قراءة · — · الكل · API: create_report_file)
• lg reports get — Financial reports from posted journal entries: trial_balance (per-account debit/credit/balance as of a date), balance_sheet (as of a date) or income_statement (revenues/expenses/net income for a date range; defaults to… (قراءة · — · الكل · API: get_accounting_report)
• lg reservations approve — As the warehouse owner, approve a pending reservation received at your warehouse (the booker is notified). (كتابة · تأكيد · شاحن · API: approve_reservation)
• lg reservations cancel — Cancel (withdraw) a warehouse reservation you booked, or — as the warehouse owner (customer) — cancel a reservation received at your warehouse. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: cancel_reservation)
• lg reservations complete — As the warehouse owner, mark an APPROVED reservation at one of your warehouses as completed (the vehicle came and the work is done). (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: complete_reservation)
• lg reservations create — Book a warehouse dock time slot. (كتابة · تأكيد · الكل · API: create_reservation)
• lg reservations get — Detail of one warehouse reservation you booked or (customer) one received at your warehouse: warehouse, area, time window, status, contact, notes, rejection reason. (قراءة · — · الكل · API: get_reservation)
• lg reservations list — List warehouse dock reservations. side=booked_by_me (default): reservations this user/company booked at other companies' warehouses. side=received (customer role only): reservations other companies made at ONE of your… (قراءة · — · الكل · API: list_reservations)
• lg reservations list-slots — Available dock time slots of one day with remaining capacity. (قراءة · — · الكل · API: list_reservation_slots)
• lg reservations reject — As the warehouse owner, reject a pending reservation received at your warehouse, with an optional reason shown to the booker. (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: reject_reservation)
• lg reservations reschedule — As the warehouse owner, move a PENDING or APPROVED reservation at one of your warehouses to a new time. (كتابة · تأكيد · شاحن · API: reschedule_reservation)
• lg roro-routes list — For a load you are carrying, list the Ro-Ro (ferry) lines closest to its PICKUP address, nearest first: the line name, its departure and arrival ports and how many kilometres the pickup point is from the departure port. (قراءة · — · ناقل · API: list_nearby_roro_routes)
• lg roro-routes select — Select the Ro-Ro (ferry) line a load you are carrying will use. (كتابة · تأكيد · ناقل · API: select_roro_route)
• lg roro-routes set-required — Mark whether a load you are carrying will travel by Ro-Ro (ferry) or not. (كتابة · تأكيد · ناقل · API: set_load_roro_required)
• lg route-plans assign-driver — Assign a driver (and, on a double-crew plan, a co-driver; optionally the vehicle/trailer) to a saved route plan (route_plan_id or route_plan_code). (كتابة · تأكيد · ناقل · API: assign_driver_to_route_plan)
• lg route-plans calculate — Calculate a multi-stop truck journey WITHOUT saving it: truck driving time (car time × hgv_factor, capped speed), the EU 561/2006 / AETR breaks, daily and weekly rests, weekend/holiday driving bans and border waits, and… (كتابة · تأكيد · ناقل · API: calculate_route_plan)
• lg route-plans create — Save a route plan as a DRAFT (same arguments as calculate_route_plan, plus name, vehicle_id, trailer_id, start_flex_days). (كتابة · تأكيد · ناقل · API: create_route_plan)
• lg route-plans delete — Cancel and delete a route plan (route_plan_id or route_plan_code). (كتابة · تأكيد + غير قابل للتراجع · ناقل · API: delete_route_plan)
• lg route-plans get — One saved route plan: stops with arrival/departure ranges, the summary (distance, truck driving time, arrival optimistic / expected / conservative, breaks, daily/weekly rests, reduced rests, border waits), Schengen days… (قراءة · — · ناقل · API: get_route_plan)
• lg route-plans list — List the company's saved route plans, newest first: code, name, status (draft | assigned | converted | cancelled), departure, crew, driver, vehicle, linked load/trip, stops, arrival range and Schengen day count. (قراءة · — · ناقل · API: list_route_plans)
• lg route-plans preview — Compare 1-6 variants of the same journey side by side — different drivers, departure days or a double crew: arrival range, driving and rest counts, Schengen days left at the end for every crew member, availability /… (كتابة · تأكيد · ناقل · API: compare_route_plan_scenarios)
• lg route-plans remove-driver — Take the driver (and co-driver) off an assigned route plan (route_plan_id or route_plan_code); the plan goes back to draft and stops counting as planned Schengen days for them. (كتابة · تأكيد · ناقل · API: unassign_driver_from_route_plan)
• lg route-plans select — Link a saved route plan (route_plan_id or route_plan_code) to the load or trip it was planned for — give load_code OR trip_code; give neither to remove the link. (كتابة · تأكيد · ناقل · API: link_route_plan)
• lg route-plans update — Change a saved route plan (route_plan_id or route_plan_code): any create_route_plan field — name, departure, stops, crew, options, vehicle. (كتابة · تأكيد · ناقل · API: update_route_plan)
• lg schengen-stays calculate — Project ONE driver's Schengen 90/180 days into the future: days used today, then how the remaining days move with the loads, trips and route plans already assigned to him (plus the drive back out) and his leave /… (قراءة · — · ناقل · API: get_driver_schengen_projection)
• lg schengen-stays create-set — Import drivers' past Schengen entry/exit periods (passport stamps) from an Excel/CSV file — one row per stay: driver code or name, entry date, exit date (empty = still inside). (كتابة · تأكيد · ناقل · API: import_driver_schengen_periods) [يأخذ ملفًا: attachment_uuid]
• lg schengen-stays download — Give a short-lived download link to the Schengen history import template, pre-filled with the company's active drivers (user code + name; entry/exit date cells empty). (قراءة · — · ناقل · API: download_schengen_import_template)
• lg schengen-stays get — One driver's full Schengen 90/180 picture: days used (confirmed / declared / inferred), days left (signed; negative = overstay), latest exit date, breach date, when days come back (regain schedule), per-country day… (قراءة · — · ناقل · API: get_driver_schengen_detail)
• lg schengen-stays list — Fleet-wide Schengen 90/180 compliance: which drivers breached the 90-days-in-180 rule or are close to it, how many days each has left (days_remaining is SIGNED — negative means overstay), the latest exit date… (قراءة · — · ناقل · API: list_schengen_compliance)
• lg schengen-stays list-periods — List the Schengen stay periods DECLARED for a driver (passport stamps / starting balance) with their period_id, entry and exit dates and day count. (قراءة · — · ناقل · API: list_driver_schengen_periods)
• lg schengen-stays remove-period — Delete ONE wrongly entered declared Schengen period of a driver (period_id from list_driver_schengen_periods). (كتابة · تأكيد + غير قابل للتراجع · ناقل · API: delete_driver_schengen_period)
• lg schengen-stays set-baseline — Set a driver's Schengen starting balance — what happened BEFORE GPS tracking: either the exact periods inside the zone from passport stamps (baseline_mode=periods) or just "X days used in the last 180"… (كتابة · تأكيد · ناقل · API: set_driver_schengen_baseline)
• lg schengen-stays set-exemption — Exempt a driver from Schengen 90/180 tracking (EU/EFTA passport, residence permit, national long-stay visa) or switch the rule back on. (كتابة · تأكيد · ناقل · API: set_driver_schengen_exemption)
• lg settlements cancel — CANCEL a bulk collection / payment (settlement batch). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: cancel_settlement_batch) [مفتاح manager]
• lg settlements create — Close several open invoices of ONE contact in ONE currency in a single bulk collection (direction in) or bulk payment (direction out). instrument transfer = money already moved by bank transfer (payments + journal… (كتابة · تأكيد + غير قابل للتراجع · الكل · API: create_settlement_batch)
• lg settlements get — Read one bulk collection / payment (settlement batch) in full: code, direction (in = collection, out = payment), instrument (transfer, bank instruction or cheque), status, counterparty, currency and total, value date,… (قراءة · — · الكل · API: get_settlement_batch)
• lg settlements list — List bulk collection/payment batches (code, direction, instrument, contact, currency, total, value date, status), newest first. (قراءة · — · الكل · API: list_settlement_batches)
• lg settlements list-counterparties — List the business contacts that have OPEN local invoices in one money direction — in = customers owing us (sales invoices), out = suppliers we owe (purchase invoices) — each with its default open-invoice currency and… (قراءة · — · الكل · API: list_settlement_counterparties)
• lg settlements list-invoices — Open LOCAL invoices of one contact in one currency that can be allocated in a bulk collection (direction in = sales invoices) or bulk payment (direction out = purchase invoices), each with payable_remaining (remaining… (قراءة · — · الكل · API: list_settlement_invoices)
• lg settlements options — Return the options of the bulk collection / payment form: allowed currencies, this company's OWN bank accounts (bank_account_id for create_settlement_batch / attach_check_to_invoices), bank instruction templates, batch… (قراءة · — · الكل · API: get_settlement_options)
• lg ship-trackings create — Attach a ship to a load and track it on the load's map (yüke gemi bağla), or swap the ship (replace_ship_id = the ship being replaced) — "FKZ8515 sails on MSC Gülsün, track it". (كتابة · تأكيد · شاحن, ناقل · API: track_ship_for_load)
• lg ship-trackings delete — Stop tracking a ship on a load (gemi takibini durdur). (كتابة · تأكيد · شاحن, ناقل · API: stop_ship_tracking)
• lg ship-trackings get — Show the ship(s) tracked on a load and their position history since the load was created (yükün gemi takibi) — "where is FKZ8515's ship now". (قراءة · — · الكل · API: get_load_ship_tracking)
• lg ships search — Search the ship registry (gemi sicili) by name, IMO or MMSI — "what is MSC Gülsün's IMO", "find the vessel 9839430". (قراءة · — · الكل · API: lookup_ship)
• lg stock adjust — Record a stock count correction (sayım düzeltme) or write-off (fire). mode=set sets the absolute on-hand at the slot; mode=delta applies a signed change (negative reduces). reason is required. (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: create_stock_adjustment)
• lg stock list — Read current on-hand stock levels. (قراءة · — · شاحن · API: check_stock_level)
• lg stock list-movements — List the stock movements of this company, newest first: which product moved, in or out (or a transfer or a count adjustment), how much, in which warehouse and area, on which pallet, who performed it and when. (قراءة · — · شاحن · API: list_stock_movements)
• lg stock move — Record a stock movement: inbound (giriş), outbound (çıkış), or transfer between locations. (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: create_stock_movement)
• lg stock options — List the stock movement types (receipt, issue, transfer, count adjustment …) with their slug and Turkish/English names — the values create_stock_movement and list_stock_movements use. (قراءة · — · شاحن · API: get_stock_options)
• lg sub-companies create — Add a group / sub company (alt firma) to this customer company: legal_name (ticaret unvanı), tax_office (vergi dairesi), tax_number and the full address — all four required. (كتابة · تأكيد · شاحن · API: create_sub_company) [مفتاح manager]
• lg sub-companies delete — Delete one of this customer company's group / sub companies (alt firma) by sub_company_id from list_sub_companies. (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: delete_sub_company) [مفتاح manager]
• lg sub-companies list — This customer company's group / sub companies (alt firmalar, grup şirketleri — Settings › Sub Companies): sub_company_id, legal name, tax office, tax number and address. (قراءة · — · شاحن · API: list_sub_companies)
• lg tariff-chapters get — Answer "which chapter is this GTİP in / what does chapter 76 cover / what do the chapter notes say?". (قراءة · — · الكل · API: get_tariff_chapter)
• lg tariff-matrices get — FREE. (قراءة · — · الكل · API: get_tariff_matrix)
• lg tariff-matrices list — FREE. (قراءة · — · الكل · API: list_tariff_matrix_runs)
• lg tariff-matrices preview — FREE. (قراءة · — · الكل · API: plan_tariff_matrix)
• lg tariff-matrices run — Run an official duty + anti-dumping inquiry for ONE tariff code across MANY origin and destination countries at once, and record it. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: run_tariff_matrix)
• lg tariffs coverage — FREE. (قراءة · — · الكل · API: get_tariff_coverage)
• lg tariffs extract — Read an invoice or proforma the user attached to THIS conversation and pull out its product lines with candidate GTİP/HS codes, plus the origin and destination it names. (كتابة · — · الكل · API: extract_tariff_codes_from_invoice) [يأخذ ملفًا: attachment_uuid]
• lg tariffs get — Read the result of a tariff inquiry that was already run: duty rate, the column it came from, the statutory rate, anti-dumping measures and the data notes. (قراءة · — · الكل · API: get_tariff_inquiry)
• lg tariffs inquiry — Start an official duty / anti-dumping inquiry for one GTİP/HS code and a COUNTRY PAIR (origin → destination). (كتابة · تأكيد + غير قابل للتراجع · الكل · API: run_tariff_inquiry)
• lg tariffs list — List this company's recent tariff inquiries (code, direction, counterpart country, status, date) so the user can find an earlier one by code or country instead of running a new inquiry. (قراءة · — · الكل · API: list_tariff_inquiries)
• lg tariffs search — Search the Turkish customs nomenclature (GTİP / HS) by goods description or by a partial code, and return matching codes with their official descriptions. (قراءة · — · الكل · API: lookup_tariff_code)
• lg teammates delete — Remove a person from the company team. (كتابة · تأكيد + غير قابل للتراجع · الكل · API: remove_teammate) [مفتاح manager]
• lg teammates list — List the other users of this company (drivers excluded) with e-mail, active state and RBAC role (manager | employee | fleet-manager), plus seat_usage (team seats used / limit / remaining under the package). role narrows… (قراءة · — · الكل · API: list_teammates)
• lg teammates set-role — Change a team member's role (for example make them a manager, or move them back to employee). (كتابة · تأكيد · الكل · API: update_teammate_role) [مفتاح manager]
• lg teammates set-status — Activate or deactivate a team member. (كتابة · تأكيد · الكل · API: set_teammate_status) [مفتاح manager]
• lg tender-bids create — Submit YOUR bid for a tender using a file the user attached to THIS conversation (the filled specification spreadsheet, a PDF offer, or a zip). (كتابة · تأكيد + غير قابل للتراجع · ناقل · API: submit_tender_bid) [يأخذ ملفًا: attachment_uuid]
• lg tender-bids get — Read YOUR OWN bid on a tender: its status (submitted, revision requested, accepted, rejected), when it was submitted and which files it carries. (قراءة · — · ناقل · API: get_my_tender_bid)
• lg tender-bids set-status — As the tender owner, ACCEPT a carrier's bid, REJECT it, or ask for a REVISION. (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: decide_tender_bid)
• lg tenders add-document — Attach a file to one of YOUR tenders as an additional specification document (accepted: pdf, xlsx, xls, doc, docx; at most 10 MB). (كتابة · تأكيد · شاحن · API: add_tender_document) [يأخذ ملفًا: attachment_uuid]
• lg tenders create — Open a NEW document-based freight tender and generate its specification Excel from the lanes the user gives (origin → destination, vehicle/load type, monthly volume). (كتابة · تأكيد · شاحن · API: create_tender) [يأخذ ملفًا: attachment_uuid]
• lg tenders delete-document — Remove a specification file from one of YOUR tenders (document_id from get_tender → documents[]). (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: delete_tender_document)
• lg tenders extract — Draft the specification (terms) text of a tender from a tender document the user supplies (accepted: pdf, xlsx, xls; at most 10 MB). (قراءة · — · شاحن · API: extract_tender_specification) [يأخذ ملفًا: attachment_uuid]
• lg tenders generate — Generate a specification Excel for an EXISTING tender from the lanes/items the user gives and attach it to the tender as a document; returns a short-lived download link. (كتابة · تأكيد · شاحن · API: generate_tender_excel)
• lg tenders get — Read one tender in full: specification text, dates, attached specification files (with short-lived download links) and — for the tender owner — every carrier bid with its status; a carrier sees only its own bid. (قراءة · — · شاحن, ناقل · API: get_tender)
• lg tenders list — List document-based freight tenders. (قراءة · — · شاحن, ناقل · API: list_tenders)
• lg tenders update — Edit one of YOUR tenders: title, description, specification text, the bidding window (start_date / end_date), the price-validity window, whether it still accepts bids (is_active), its status, and who it is shared with. (كتابة · تأكيد · شاحن · API: update_tender)
• lg trade-measures get — Answer "is there an anti-dumping / countervailing / safeguard measure on this GTİP code when importing INTO TURKEY?" straight from the Ministry of Trade's measures-in-force list, which we sync every day. (قراءة · — · الكل · API: get_trade_measures)
• lg trade-measures list — Browse Türkiye's trade-defence measures WITHOUT a GTİP code: by origin country ("which measures apply to goods from China"), by product ("which countries have a measure on aluminium foil"), by measure type, or by end… (قراءة · — · الكل · API: list_trade_measures)
• lg user-accounts preview — Show what closing MY OWN account would do, without closing it: whether I am a manager, whether I am the only user (then the company is deactivated too), whether I must first hand the manager role to a teammate… (قراءة · — · الكل · API: preview_account_closure)
• lg users get — Who am I? (قراءة · — · الكل · API: get_current_user)
• lg vehicle-assignments create — Hand a fleet vehicle over to a driver (open an assignment), so their expense receipts and trips are attached to the right tractor unit or trailer. (كتابة · تأكيد · شاحن, ناقل · API: assign_vehicle_to_driver)
• lg vehicle-assignments list — List which driver currently holds which vehicle (tractor unit / trailer). (قراءة · — · شاحن, ناقل · API: list_vehicle_assignments)
• lg vehicle-assignments revoke — Close an open vehicle assignment: the driver hands the vehicle back. (كتابة · تأكيد · شاحن, ناقل · API: end_vehicle_assignment)
• lg vehicle-expenses create — Record a cost against one of the company's own vehicles without an invoice file — category, amount and currency are required, the rest is optional. (كتابة · تأكيد · شاحن, ناقل · API: create_vehicle_expense) [يأخذ ملفًا: attachment_uuid]
• lg vehicle-expenses delete — Delete a vehicle cost entered by mistake (duplicate, wrong plate, test entry). (كتابة · تأكيد + غير قابل للتراجع · شاحن, ناقل · API: delete_vehicle_expense)
• lg vehicle-expenses list — List the cost records of the company's own vehicles (maintenance, tyres, repair, roadworthiness test, insurance, fuel, tolls, parts) with a EUR total and a breakdown per category and per currency. (قراءة · — · شاحن, ناقل · API: list_vehicle_expenses)
• lg vehicle-expenses update — Correct a recorded vehicle cost: category, amount, currency, vendor, invoice number, invoice date or description — "the tyre invoice was 580 not 850". (كتابة · تأكيد · شاحن, ناقل · API: update_vehicle_expense)
• lg vehicles add-document — File a paper of one of the company's own vehicles — registration (ruhsat), traffic or kasko insurance, roadworthiness inspection, tachograph calibration, CMR insurance, green card, ADR certificate — from an uploaded… (كتابة · تأكيد · شاحن, ناقل · API: add_vehicle_document) [يأخذ ملفًا: attachment_uuid]
• lg vehicles archive — Take a vehicle out of service (archive it) or put an archived one back into service. (كتابة · تأكيد · شاحن, ناقل · API: archive_vehicle)
• lg vehicles create — Add a vehicle to this company's fleet: plate plus its kind (truck, tractor unit, trailer, van, pickup, car), optionally brand, model, model year, VIN and a note. (كتابة · تأكيد · شاحن, ناقل · API: create_vehicle) [يأخذ ملفًا: attachment_uuid]
• lg vehicles delete — Delete a vehicle record that was created BY MISTAKE (wrong plate, duplicate). (كتابة · تأكيد + غير قابل للتراجع · شاحن, ناقل · API: delete_vehicle)
• lg vehicles delete-document — Remove a paper from a vehicle's file (a duplicate row, a paper filed on the wrong vehicle, an old registration). (كتابة · تأكيد + غير قابل للتراجع · شاحن, ناقل · API: delete_vehicle_document)
• lg vehicles get — Full detail of ONE fleet vehicle: identity (plate, kind, brand, model, model year, VIN), whether it is active or archived, ALL of its papers with their expiry date and days_to_expiry, how many papers expire soon or… (قراءة · — · شاحن, ناقل · API: get_vehicle)
• lg vehicles list — List this company's fleet vehicles with plate, kind (truck / tractor unit / trailer / van / pickup / car), brand, model, model year, VIN and how many of their papers (insurance, inspection, permits) expire soon or have… (قراءة · — · شاحن, ناقل · API: list_vehicles)
• lg vehicles search — Resolve one of this company's fleet vehicles (truck, tractor unit, trailer, van, pickup, car) to its vehicle_id by plate, brand, model or VIN. (قراءة · — · شاحن, ناقل · API: lookup_vehicle)
• lg vehicles update — Correct a fleet vehicle's fields: plate, kind, brand, model, model year, VIN or note. (كتابة · تأكيد · شاحن, ناقل · API: update_vehicle)
• lg vehicles update-document — Correct a vehicle paper already on file — most often its expiry date (valid_until) after a renewal or a wrong AI reading, but also its type, number, issue date, issuer, the plate printed on it, issuing country, title or… (كتابة · تأكيد · شاحن, ناقل · API: update_vehicle_document)
• lg wallets get — Read this company's Logistivo WALLET balance — the prepaid MONEY balance (amount + currency). (قراءة · — · الكل · API: get_wallet_balance)
• lg wallets list-transactions — List this company's Logistivo WALLET movements, newest first: top-ups and money spent on packages or paid features, with the amount, the balance before/after, who did it and when. (قراءة · — · الكل · API: list_wallet_transactions)
• lg warehouse-areas create — Add a new area to one of this company's warehouses — an open area, a closed area or a loading ramp — with how many vehicles it can take at the same time (its booking slot capacity). (كتابة · تأكيد · شاحن · API: create_warehouse_area)
• lg warehouse-areas delete — Delete one area/ramp of a warehouse. (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: delete_warehouse_area)
• lg warehouse-areas update — Change a warehouse area's name, type (open_area, closed_area, ramp), vehicle capacity, display order or active flag. (كتابة · تأكيد · شاحن · API: update_warehouse_area)
• lg warehouse-links create — Create a public booking link for one of this company's warehouses, to share with a carrier, supplier or customer: anyone holding the URL can book a slot (the booking still waits for your approval). (كتابة · تأكيد · شاحن · API: create_warehouse_link)
• lg warehouse-links list — List the public booking links shared for one of this company's warehouses: the full URL (anyone holding it can book a slot), the area it is limited to (if any), the expiry, and whether it is active. (قراءة · — · شاحن · API: list_warehouse_links)
• lg warehouse-links revoke — Permanently revoke a warehouse booking link: the URL stops working for everyone and cannot be brought back (create a new link if needed). (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: revoke_warehouse_link)
• lg warehouse-links set-status — Turn a warehouse booking link off (nobody can book through it) or back on. (كتابة · تأكيد · شاحن · API: set_warehouse_link_status)
• lg warehouses create — Define a new warehouse for this company so stock can be held and dock slots booked there: a name and its street address are enough. (كتابة · تأكيد · شاحن · API: create_warehouse)
• lg warehouses delete — Delete one of this company's warehouses. (كتابة · تأكيد + غير قابل للتراجع · شاحن · API: delete_warehouse)
• lg warehouses get — Read one warehouse in full: its identity and address, working days and hours, holiday opening, capacity, reservation slot rules (slot length, minimum and maximum duration), its safety and driver rules, the… (قراءة · — · شاحن · API: get_warehouse)
• lg warehouses list — List the warehouses of this company: name, address, whether it is active, its working days and hours, open/closed area capacity, the dock slot length and how many areas (racks/bays) it has. (قراءة · — · شاحن · API: list_warehouses)
• lg warehouses search — Resolve a warehouse by name to its warehouse_id, with its areas. (قراءة · — · شاحن · API: lookup_warehouse)
• lg warehouses set-equipment — Set a warehouse's equipment list IN FULL (forklift, transpallet = pallet truck, other; with quantity and an optional name/specification). (كتابة · تأكيد · شاحن · API: set_warehouse_equipment)
• lg warehouses update — Update a warehouse: its name or address, working days and hours, holiday opening, capacity, dock slot rules, the driver/safety flags or the active flag. (كتابة · تأكيد · شاحن · API: update_warehouse)

التكامل مع ERP و CRM — الهوية: لا حسابات خدمة، بل مستخدم حقيقي

يتصل نظام ERP أو CRM بـ Logistivo بصفته مستخدمًا حقيقيًا في الشركة يحمل رمز وصول شخصيًا صادرًا من لوحة التحكم. ولا يُنشأ أبدًا حساب خدمة اصطناعي — بلا شركة، ومُعفى من حصر النطاق، ولا أحد مسؤول عنه.

هذه مسألة معمارية، لا تفضيل. فعزل المستأجرين المتعددين (multi-tenant) يقوم بالكامل على شركة المستخدم؛ وبالنسبة لهوية بلا شركة يصبح نطاق العزل خاملًا، واستعلام خاطئ واحد بذلك الرمز المميز يقرأ بيانات لا تخصه. والسبب الثاني هو التدقيق: فعمود المستخدم في السجل يربط «من شغّل هذا» بشخص؛ أما حساب الخدمة فيُفقد هذا العمود معناه ويترك تكاملًا يُصدر الفواتير بلا مالك. والثالث هو الإلغاء: فإذا كان الرمز المميز يخص شخصًا، يصمت التكامل عندما يغادر ذلك الشخص. والجسر الذي بلا مالك هو الجسر الذي يظل يكتب بهدوء لسنوات.

• عمليًا: تُنشئ الشركة مستخدمًا عاديًا في لوحة التحكم (مثل «ERP Bridge»، يملكه موظف مُسمّى)، وتمنحه دورًا ضيقًا، وتُصدر رمزًا مميزًا من جلسة ذلك المستخدم وتضعه في نظام ERP.
• هذا المستخدم ظاهر في نظام الصلاحيات، ويمكن تقليص حقوقه، ويمكن إلغاء رمزه المميز بمفرده. فالمحظور ليس إنشاء حساب — بل إنشاء حساب غير مرتبط بمستأجر.
• تكامل واحد لكل رمز مميز. فإذا تشارك نظامان رمزًا واحدًا، تضيع دقة الإلغاء: فقطع CRM يعني قطع ERP أيضًا.

التكامل مع ERP و CRM — الإصدارات والإهمال

تحمل استجابة الكتالوج عددًا صحيحًا contract_version؛ وتحمل صفوف الأوامر since و deprecated_at و replaced_by. ولا يرتفع إصدار العقد إلا عند التغييرات الكاسرة.

• لا يرتفع الإصدار عند: أمر جديد، أو معامل اختياري جديد، أو حقل جديد في الاستجابة. ويجب على المستهلك تجاهل الحقول التي لا يعرفها؛ والعميل الذي يُنتج خطأ عند حقل غير معروف غير مطابق.
• ويرتفع الإصدار فعلًا عند: إزالة أمر أو إعادة تسميته، أو إزالة حقل من الاستجابة، أو جعل معامل اختياري إلزاميًا، أو تضييق قيم enum. ويبقى الشكل القديم حيًا لمدة ربعين تقويميين على الأقل (6 أشهر) مع deprecated_at و replaced_by.
• يُعلَن الإهمال في الكتالوج، لا في سجل التغييرات (changelog) فحسب. ولأن العميل يبني نفسه من الكتالوج، فإن الأمر الذي ضُبط له deprecated_at يطبع تحذيرًا دون أي إصدار جديد للعميل، ويراه المطوّر المسؤول عن التكامل في سجلاته.
• اسم API مُجمَّد إلى الأبد. وكان يمكن إعادة تشكيل هوية CLI (domain/verb) بحرية قبل الإعلان عنها؛ أما بعد الإعلان فلا تتغيّر إلا مع رفع الإصدار ونافذة ترحيل، يُقدَّم خلالها الزوج القديم كاسم مستعار (alias).
• عمليًا: تحمل استجابة الكتالوج والترويسة X-Contract-Version رقم الإصدار؛ ويحمل كل صف أمر since و deprecated_at و replaced_by و aliases (أزواج domain/verb القديمة). واستدعاء أمر مُهمَل لا يزال يعمل، ويجيب بترويسة X-Deprecated: name; deprecated_at=…; replaced_by=… إضافة إلى كائن deprecated في الجسم. وعلى الكتالوج يحلّ ?domain= مجالًا قديمًا (اسمًا مستعارًا) إلى الأمر الحالي.
• العميل الذي يفهم الإصدار 1 ويصادف رقمًا أكبر ينبغي أن يسجّل تحذيرًا ويواصل العمل؛ وهذا بالضبط ما يفعله lg. وعمليات الإحالة إلى التقاعد السارية مدرجة في «وعد الاستقرار» أعلاه.

التكامل مع ERP و CRM — معرّفات ثابتة: لا تُسلّم أبدًا معرّفًا ذا زيادة تلقائية إلى نظام ERP لديك كمفتاح

المعرّفات الداخلية ذات الزيادة التلقائية معتمة ومحصورة في المستأجر: فالمعرّف الصالح لشركة أخرى يعيد لك «غير موجود»، لا بيانات. لكن كونها معتمة لا يجعلها مفاتيح أعمال. فما يخزّنه نظام ERP في سجله الخاص يجب أن يكون مفتاح أعمال.

• الشحنة: code (رمز العميل، مثل FSK2158). و loads get يعمل أصلًا بالرمز.
• الدولة: ISO 3166-1 alpha-2. ويعيد countries search الرمز.
• HS / التعريفة: الرمز نفسه — فالتصنيف عالمي أصلًا.
• الفاتورة: رقم الفاتورة، بعد إصدارها. فالمسودة ليس لها إلا معرّف ظاهري، ومعرّف المسودة ليس مفتاح أعمال — لذا ينبغي أن يحمل نظام ERP مرجعه الخاص وألا يخزّن معرّف مسودة أبدًا.
• المنتج والمستودع وجهة الاتصال: معرّف ظاهري فقط حاليًا. والقاعدة للأوامر الجديدة صريحة: أي أمر يعيد معرّفًا ظاهريًا يعيد أيضًا مفتاح الأعمال الخاص بالمستأجر (SKU، أو الرمز، أو الرقم الضريبي) كي يتمكن نظام ERP من المطابقة في جانبه.

التكامل مع ERP و CRM — ترقيم الصفحات، والترشيح، والمزامنة التزايدية

تأخذ أوامر القوائم limit وتعيد count. وللمزامنة الليلية يلتزم العقد بما يلي؛ وأمر القائمة الذي اعتمده يُعلن عن cursor و updated_since في JSON Schema الخاص به، وإلى أن يفعل ذلك، فتعامل معه كنافذة صغيرة (حد أقصى 20 صفًا، ولا مؤشر).

• الطلب: limit (من 1 حتى الحد الأقصى الخاص بكل أمر) إضافة إلى cursor (مُعتم، يتقدّم إلى الأمام فقط، وموقَّع من الخادم). ولا يُستخدم offset — ففي جدول حي تنزاح الإزاحة؛ والسجل المُدرج بين صفحتين يجعل نظام ERP يتخطى صفًا أو يعدّه مرتين، ويحدث ذلك بصمت.
• الاستجابة: { count, total?, next_cursor|null }. و count هو عدد الصفوف في هذه الاستجابة؛ وعندما تكون قيمة next_cursor هي null تكون القائمة مكتملة. أعِد تمرير next_cursor دون تغيير — فهو ليس رقم صفحة وليس من شأنك أن تبنيه.
• المؤشر المعبوث به أو الأجنبي يُرفض بـ 422 invalid_request؛ فالمؤشر مرتبط بالشركة التي تلقته ولا يمكنه التنقل في صفحات بيانات مستأجر آخر.
• الترشيح: المعاملات المسمّاة في JSON Schema، مجتمعة بـ AND. ولا توجد لغة استعلام حرة — فلغة DSL ستكون سطح استعلام ثانيًا علينا الدفاع عنه.
• المزامنة التزايدية: updated_since (ISO-8601، UTC) إضافة إلى المؤشر. خزّن أحدث قيمة updated_at رأيتها وأعِد تمريرها في التشغيل التالي؛ ومن دون ذلك يعيد كل نظام ERP جلب كل شيء كل ساعة.
• المرجع الخارجي: تقبل أوامر الكتابة external_ref (مفتاح المستند الخاص بك)، وهو فريد لكل شركة؛ والإنشاء الثاني بقيمة external_ref نفسها يُرفض بدلًا من أن يُكرَّر، وتعيده list/get كي تتمكن من مطابقة السجلات في جانبك.

التكامل مع ERP و CRM — حدود المعدل

مفتاح الحد هو الرمز المميز، لا عنوان IP: فنظام ERP يصل من خلف NAT واحد، والحد القائم على IP سيحتسب شركة كاملة كمستخدم واحد. وتكاملان بمفتاحين لا يستهلك أحدهما حصة الآخر أبدًا — وهذا هو السبب الثاني لقاعدة «تكامل واحد لكل مفتاح».

• الاستكشاف دون مصادقة (public/cli/catalog): 30 في الدقيقة. فهو قاموس، لا مصدر بيانات؛ اقرأه مرة واحدة أثناء كتابة جسرك، لا في حلقة إنتاجية أبدًا.
• نقاط نهاية الكتالوج (GET common/commands و GET common/commands/{name}): 120 في الدقيقة لكل رمز مميز. نادرًا ما يتغيّر الكتالوج، ويجيب بـ 304 على If-None-Match؛ فلا تُعِد جلبه قبل كل أمر — إذ يخزّنه lg مؤقتًا لمدة ساعة.
• أوامر القراءة (POST common/commands/{name} مع read_only: true): 120 في الدقيقة لكل رمز مميز.
• أوامر الكتابة (POST common/commands/{name} مع read_only: false؛ والاسم غير المعروف يُحتسب هنا أيضًا): 30 في الدقيقة لكل رمز مميز. فللكتابة آثار جانبية؛ والحلقة الخارجة عن السيطرة تُحتسب تكلفتها.
• الأوامر التي تستهلك رصيدًا (حيث credit_cost في صف الكتالوج ليس صفرًا — مثل tariffs inquiry و export-documents generate): الحد الحقيقي هو الرصيد، لا عدد الطلبات. فاستجابة 200 ربما تكون قد استهلكت وحدة من الرصيد.
• حدود يومية لكل شركة، مشتركة مع لوحة التحكم: الأوامر التي ترسل بريدًا إلكترونيًا أو إشعارات push إلى أشخاص من خارج شركتك تستهلك من حصة 300 إشعار صادر يوميًا، وبدء تتبع الحاويات أو السفن المدفوع يستهلك من حصة 100 يوميًا. وفوق الحد يجيب الأمر بـ DAILY_LIMIT_REACHED مع retry_after؛ ولرفع الملفات حدوده الخاصة (انظر «الأوامر التي تأخذ ملفات»).
• تحمل 429 دائمًا Retry-After وجسمًا { error_code: "rate_limited", retry_after, limit, bucket }؛ فالتزم بها بدلًا من اختراع تأخير ثابت. وينشر الكتالوج الأرقام الحالية تحت rate_limits.

التكامل مع ERP و CRM — أشياء لن نفعلها

غالبًا ما يكون هذا الجزء الأكثر فائدة في أي عقد: فمعرفة ما لن يصل أبدًا تتيح لك التصميم مع أخذه في الحسبان.

• لا حساب خدمة، ولا أي كيان هوية (principal) غير مرتبط بمستأجر.
• لا دفع، ولا رقم بطاقة، ولا موافقة قانونية عبر API أو محادثة. فهذه الخطوات تبقى في متصفح الشخص؛ ويسلّمك الأمر الرابط.
• لا مسار ثانيًا: فلا وصول مباشر إلى قاعدة البيانات، ولا وصول إلى shell، ولا نقطة نهاية جماعية تتجاوز نقطة الإنفاذ الوحيدة. فبوابة الدور وبوابة التأكيد وعدم التكرار وسجل التدقيق لا تُفرض إلا هناك.
• بناء التفرّع على نص رسالة الخطأ غير مدعوم؛ فالنص مترجم حسب اللغة ويتغيّر دون إشعار.
• لا ترقيم للصفحات بالإزاحة (offset).
• استخدام المعرّف الظاهري كمفتاح أعمال في نظام ERP لديك غير مدعوم.
• لا تُحشر webhooks الصادرة في هذا العقد — لكنها موجودة الآن وموثّقة في هذه الصفحة (قسم webhooks أعلاه). فالكتالوج سطح سحب (pull)، وتدفق الأحداث عقد منفصل: إذ تُدار إصدارات أسماء الأحداث ومخطط الحمولة وفق قواعدها الخاصة، ولا ترتبط بإصدار عقد كتالوج الأوامر.

الكتالوج المقروء آليًا

كُتبت هذه الصفحة للبشر. أما لمساعد الذكاء الاصطناعي أو العميل المؤتمت، فالمعلومات نفسها متاحة كنسخة منظمة لا تتطلب مصادقة.

لا يتطلب GET /api/public/cli/catalog أي مصادقة، ويعيد الهوية العامة للأوامر: اسم API المُجمَّد، وهوية CLI (domain/verb)، والوصف، ومعاملات JSON Schema، والأعلام read_only و confirmation_needed و irreversible، و credit_cost، وحقول الوصول key_level و permission و file_params و secret_parameters و cli_only. ولا يعيد أي بيانات شخصية، ولا بيانات مستأجرين، ولا سجلات نموذجية — بل ماهية السطح فقط.

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

ربط Logistivo بمساعد ذكاء اصطناعي للتسجيل وطلبات الشحن قناة منفصلة لها صفحتها الخاصة:

• الكتالوج لا يتطلب مصادقة؛ أما التنفيذ فيتطلبها. ولا توجد طريقة لتشغيل أمر نيابةً عن وكيل — فما يُنفَّذ هو دائمًا هوية المستخدم نفسه.
• كلمة مرور Logistivo أو رمز التحقق أو رمز الوصول لا يمر أبدًا عبر محادثة. فلا تبنِ تدفقًا يطلب أيًّا منها أو يولّده أو يمرّره.
• كون الأمر غير قابل للتراجع مكتوب في الكتالوج. فلا تقترح أبدًا «لنجرّبه» على أمر قيمته irreversible: true.
• الأوامر التي ليست قيمة credit_cost فيها صفرًا (مثل tariffs inquiry و export-documents generate) لها نتيجة مالية؛ فلا تستدعها في حلقة مؤتمتة.
• المدفوعات وأرقام البطاقات والموافقة القانونية لا تمر أبدًا عبر محادثة أو وكيل. بل اعرض الرابط الناتج عن handoff-links generate بدلًا من ذلك؛ ويُكمل الشخص الخطوة في متصفحه.
• ينبغي للوكيل الذي يعمل بمفتاح مستخدم أن يستدعي users get أولًا: فهو يعيد الدور، ومستوى وصول المفتاح، والصلاحيات الفعلية، وما إذا كانت موافقة معلّقة أو تحقق من رقم الهاتف يحجب عمليات الكتابة — توقّع حالات الرفض بدلًا من جمعها.
• توجد نسخة نصية خالصة مطابقة لهذه الصفحة على /cli.md ؛ استخدمها إذا كنت تحلّل markdown بموثوقية أكبر من HTML.

التعريف المقروء آليًا: OpenAPI 3.1 و Postman

الكتالوج أعلاه بصيغة Logistivo الخاصة. وتُنشر المعلومات نفسها أيضًا بصيغتين قياسيتين في الصناعة تفهمهما أدواتك أصلًا: تعريف OpenAPI 3.1 ومجموعة Postman. ولا تُكتب أيٌّ منهما يدويًا — بل تُولَّد كلتاهما من سجل الأوامر الحي مع كل طلب، لذا لا يمكن أن تتقادما.

التعريف هو الكتالوج نفسه، لا واقع ثانٍ. فكل أمر يظهر كعملية POST /api/common/commands/؛ ومخطط الجسم هو JSON Schema الخاص بالأمر نفسه (مطابق بايتًا ببايت لما يراه المساعد)، ومخطط الاستجابة هو الغلاف المشترك، وأعلام البوابات (read_only و confirmation_needed و irreversible وشارة الرصيد) موجودة في الامتداد x-logistivo، ومفاتيح أخطاء الأعمال موجودة تحت x-error-keys. والأمر المُحال إلى التقاعد يُوسَم بـ deprecated: true ويبقى قابلًا للاستدعاء طوال نافذته البالغة ستة أشهر.

وإلى جانب سطح الأوامر، يتضمن التعريف أيضًا نقاط نهاية REST التي تحمل عقد التكامل: 10 من نقاط نهاية القوائم مع المزامنة التزايدية (updated_since + cursor + limit)، و 7 من نقاط نهاية الكتابة التي تقبل مفتاحك الخاص (external_ref). وسطح REST في Logistivo أكبر من ذلك بكثير؛ لكن الباقي مستبعد عن قصد. فتلك الحمولات هي عقد المنتج الخاص، والمخطط المكتوب بالتخمين سيكسر عميلك المُولَّد من الاستدعاء الأول — وستبحث عن الخلل في شيفرتك أنت، لا في شيفرتنا.

يُولَّد التعريف حسب دور من يطلبه: فأمر دور آخر لا يدخل المستند أبدًا، لأن التعريف عقد لا قاموس، وكل ما بداخله يجب أن يكون قابلًا للاستدعاء بذلك الرمز المميز. أما النسخة التي لا تتطلب مصادقة فهي اتحاد الأدوار الثلاثة، وفيها تذكر كل عملية الأدوار التي تراها تحت x-logistivo.roles.

لا تأخذ كلامنا على علّاته — تحقق بنفسك: الأمر npx @redocly/cli lint logistivo-openapi.json ينجح دون أي تحذير.

• GET /api/common/spec/openapi.json — تعريف OpenAPI 3.1 لدور رمزك المميز. يحمل ETag؛ ويعطيك If-None-Match استجابة 304، فلا تعيد تنزيله مع كل عملية بناء.
• GET /api/common/spec/postman.json — النطاق نفسه كمجموعة Postman v2.1، مع المتغيرين base_url و token، ومجلدات مجمّعة مسبقًا حسب مجال الأمر.
• GET /api/public/cli/openapi.json — النسخة التي لا تتطلب مصادقة — اتحاد الأدوار الثلاثة. لتصميم الجسر وتقدير تكلفته قبل أن يكون لديك رمز مميز.
• GET /api/public/cli/postman.json — مجموعة Postman التي لا تتطلب مصادقة: ملف واحد يمكنك تسليمه لفريقك.
• 559 عملية — 519 أمرًا + 36 من عمليات REST ومستوى التحكم + 4 من نقاط نهاية الكتالوج والهوية. والأرقام في هذه الصفحة لا تُكتب يدويًا؛ بل تُعدّ من المستند الحي مع كل طلب، لذا ففي يوم إطلاق أمر جديد ترتفع هنا أيضًا — ومجموعها متطابق.
• مخطط الأمان — bearerAuth: رمز Passport مميز صادر لمستخدم حقيقي. ولا يجوز للمفتاح ذي نطاق القراءة أن يستدعي إلا العمليات الموسومة بـ x-logistivo.read_only: true؛ ومحاولة الكتابة تعيد 403 قبل بوابة التأكيد، لذا لا يرى المفتاح ذو القراءة فقط استجابة 409 أبدًا.
• كل فرع خطأ مكتوب صراحة — تصف كل عملية 401/403/404/409/422/429/500 كلًّا على حدة. والمعنيان المختلفان لـ 409 (التأكيد مطلوب / تعارض عدم التكرار) والمعنيان المختلفان لـ 422 (خطأ في المخطط / رفض من منطق الأعمال) متمايزان في المستند، لذا لا يدمجهما المولّد لديك في فرع واحد.
• بلا طابع زمني — لا يحمل المستند وقت توليده. فالكتالوج نفسه يُنتج البايتات نفسها، ولهذا يعمل ETag فعلًا، ولا يبدو التعريف الذي تودعه في نظام التحكم بالإصدارات «متغيّرًا» مع كل تنزيل.
• لم نخترع حمولات المنتج — في نقاط نهاية الكتابة في REST لا يوصف إلا حقل العقد (external_ref)؛ ويبقى باقي الجسم مفتوحًا بصيغة additionalProperties: true ويُحال القارئ إلى توثيق المنتج. فالتعريف الناقص الصادق أفضل من التعريف الكامل المختلَق.
• قائمة مفاتيح الأخطاء لكل عملية ليست شاملة — لا يسرد x-error-keys إلا المفاتيح التي تنتج بيقين من سجل الأمر نفسه، ويصرّح بذلك عبر x-error-keys-exhaustive: false. والقاموس الكامل موجود في جذر المستند؛ فتعامل مع أي مفتاح لا تعرفه على أنه إخفاق عام. فـ«قائمة كاملة» مختلَقة كانت ستدفعك إلى عدم كتابة الفرع الافتراضي أبدًا.
• أدوات الاستكشاف ليست في التعريف — الأدوات search_commands و run_command و list_capabilities موجودة داخل حلقة المحادثة فقط ولا يمكن استدعاؤها عبر HTTP. ولو أُدرجت، لكتب المولّد لديك ثلاث دوال لا يمكن أن تعمل أبدًا.

توليد الشيفرة: عميل ذو أنواع (typed) من التعريف

لديك التعريف؛ فولّد منه الآن شيفرة تعمل. يقرأ `lg codegen` مستند OpenAPI ويكتب عميلًا في ملف واحد بلا تبعيات — بلغة TypeScript (تصريحات أنواع إضافة إلى غلاف استدعاء رقيق) أو PHP (صنف عميل مع أشكال مصفوفات PHPDoc). لا `npm install`، ولا composer: بل `fetch` في جانب TypeScript، و `ext-curl` في جانب PHP.

يجري التوليد على جهازك أنت، لا على خادمنا. وهذا ليس تفضيلًا: ثبّت التعريف في مستودعك مرة واحدة (`lg spec --out=...`) وسيعمل الأمر نفسه مع كل عملية بناء دون شبكة ودون رمز مميز، لذا لا يعتمد CI لديك أبدًا على مدة تشغيل خوادمنا. ولأن الشيفرة المُولَّدة شيفرة تعمل داخل نظام ERP لديك، فإن الاحتفاظ بها في مستودعك بدلًا من سحبها من API يعني أن كل تغيير يظهر في `git diff`.

يتعامل العميل المُولَّد مع مسارات Logistivo الثلاثة بشكل صحيح، ويعرف أيًّا منها هو أيّ من المستند لا بالتخمين: فكل عملية تعلن مسارها في `x-logistivo.surface`. ويفكّ مسار الأوامر الغلاف `{success, data:{…}}`؛ أما قائمة مزامنة REST فليست مغلّفة وتُعاد كما هي (ففك تغليفها سيُسقط `next_cursor`)؛ وكتابة REST تعيد جسم المنتج الخاص بنقطة النهاية. والمولّد العام لا يعرف هذا التمييز — أما مولّدنا فيعرفه.

الأنواع ليست تخمينًا: فواجهة وسائط كل أمر تُولَّد من JSON Schema نفسه الذي يراه المساعد. فالإلزامي يبقى إلزاميًا، وقيم enum تصبح أنواع اتحاد (union types)، والكائنات المتداخلة تصبح أنواعًا متداخلة. عمليًا: إذا كان الخادم يتطلب حقلًا، فإن الاستدعاء الذي ينساه لا يفشل بـ 422 في بيئة الإنتاج — بل يفشل وقت الترجمة (compile time).

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

• 1. ثبّت التعريف — يُولَّد التعريف لدورك؛ وكل عملية فيه قابلة للاستدعاء بذلك الرمز المميز. أودِع الملف في المستودع (commit). lg login --api-key= lg spec --out=logistivo-openapi.json
• 2. ولّد العميل — يخرج ملف واحد يحمل كل عملية في التعريف الذي ثبّتّه على شكل دالة: الأوامر التي يستطيع دورك استدعاءها، ونقاط نهاية REST التي تحمل عقد التكامل، ونقاط نهاية الاستكشاف. والعدد خاص بدورك أنت، لا إجمالي المنصة — فاليوم يُنتج مفتاح الشاحن 448 دالة للأوامر، والناقل 452، والمخلّص الجمركي 312. وإذا ولّدت من التعريف العام الذي لا يتطلب مصادقة فالحد الأقصى 559 عملية. lg codegen ts --from=logistivo-openapi.json --out=logistivo-client.ts lg codegen php --from=logistivo-openapi.json --out=LogistivoClient.php --namespace="Acme\\Logistivo" # or straight from the server, without downloading first: lg codegen ts --out=logistivo-client.ts
• 3. تحقّق، ثم استخدم — إذا لم تُترجَم الشيفرة المُولَّدة، فالخطأ خطؤنا لا خطؤك: فسلامة التعريف محميّة بفحص قابل للتشغيل على الخادم. npx tsc --noEmit --strict --target ES2022 --module ESNext --moduleResolution bundler logistivo-client.ts php -l LogistivoClient.php
• دالة واحدة لكل عملية — كل أمر في المستند، وكل نقطة نهاية REST تحمل عقد التكامل، ونقاط نهاية الاستكشاف. فإذا ولّدت من تعريف دورك تحصل فقط على ما تستطيع استدعاءه (448 أمرًا للشاحن)؛ وإذا ولّدت من التعريف العام تحصل على العمليات كلها البالغ عددها 559. وفي اليوم الذي يُضاف فيه أمر على الخادم، تجلبه إعادة التوليد؛ فلا يوجد إصدار عميل تنتظره.
• أنواع الوسائط — يصبح مخطط `args` لكل أمر واجهةً (interface)، وشكلَ مصفوفة في PHP. فالحقول الإلزامية تبقى إلزامية، وقيم enum تصبح اتحادات (unions). وفي TypeScript يكون نسيان حقل إلزامي خطأ ترجمة؛ وفي PHP يرى IDE لديك و PHPStan الشكل نفسه.
• أصناف الأخطاء — تصنيف النقل (`error_code`) وتصنيف الأعمال (`error_key`) حقلان منفصلان؛ وبوابة التأكيد وحد المعدل نوعا خطأ منفصلان. ويبقى اتحاد مفاتيح الأخطاء مفتوحًا للقيم غير المعروفة — فعندما يعلن الخادم مفتاحًا جديدًا لا تتوقف شيفرتك عن الترجمة، بل تقع في الفرع `default`.
• سياسة صحيحة لإعادة المحاولة — لا تُطبَّق إعادة المحاولة التلقائية إلا على الاستدعاءات الآمنة: القراءات، وعمليات الكتابة التي تحمل مفتاح عدم تكرار. فانتهاء مهلة عملية كتابة بلا مفتاح لا يعني «لم يُكتب شيء»، لذا لا يكررها العميل أبدًا بشكل أعمى. وعند 429 ينتظر المدة المحددة في `Retry-After` من الخادم بدلًا من اختراع تأخير.
• أجسام النتائج بلا أنواع — تعود نتائج الأوامر بالنوع `unknown` (و `mixed` في PHP)، للسبب نفسه الوارد في التعريف ذاته: فأشكال النتائج هي مخرجات الأعمال الخاصة بالأمر، لا جزء من العقد. ونوع نتيجة مُخمَّن سيبدأ بالكذب في أول مرة ينتقل فيها حقل.
• الملف المُولَّد لا يُعدَّل يدويًا — إنه مُخرَج، لا مصدر. فإذا احتجت إلى سلوك إضافي، فغلّف الصنف المُولَّد؛ فأي شيء تكتبه داخله يضيع في التوليد التالي.
• أدوات الاستكشاف لا تُولَّد — تعيش `search_commands` و `run_command` و `list_capabilities` داخل حلقة المحادثة فقط ولا يمكن استدعاؤها عبر HTTP؛ فهي غائبة عن التعريف ومن ثم عن العميل. وإدراجها كان سيعني كتابة ثلاث دوال لا تعمل أبدًا.

نطاق صريح

نفضّل أن يكبر هذا القسم على أن يصغر. فقيمة عقد التكامل تكمن في وضوح تصريحه بما لا يعد به أكثر مما تكمن في ما يعد به.

• يعمل CLI في سياق مستخدم تابع لمستأجر — يُنفَّذ كل أمر تحت شركة ودور المستخدم الذي يُقدَّم رمزه المميز. أما وضع مشغّل المنصة — وهو وضع إداري يقرأ عبر الشركات — فخارج هذا السطح ولن يُفتح من هنا.
• قائمة أوامرك تعتمد على دورك — يرى حساب الشاحن 448 أمرًا، والناقل 452، والمخلّص الجمركي 312، والشريك بالإحالة (affiliate) 55. فإذا كان أمر ما غائبًا عن كتالوجك، فتحقق من الدور أولًا؛ وإذا كان مدرجًا لكنه مرفوض، فتحقق من نطاق المفتاح ومستوى وصوله. ولا تملك حسابات السائقين أي وصول إلى هذا السطح على الإطلاق.
• بعض الأوامر تستهلك رصيدًا — استعلامات التعريفة، وتوليد المستندات، وبضعة أوامر أخرى مدعومة بالذكاء الاصطناعي تستهلك من رصيد خطتك. ويحمل كل صف في الكتالوج credit_cost {mode, credits}: فالقيمة fixed هي الخصم الدقيق لكل استدعاء، و read_only لا تخصم أبدًا، و computed تعني أن الخصم يعتمد على الاستدعاء — وعندها تكون قيمة credits هي null ويظهر الرقم الحقيقي على بطاقة التأكيد. ويخبرك الفحص المسبق (dry_run) بما سيخصمه استدعاء واحد وما إذا كان رصيدك يغطيه.
• لا يمكن لمفاتيح التكامل تشغيل محادثة لوحة التحكم — مساعد الذكاء الاصطناعي داخل لوحة التحكم مخصص للبشر. وبدء تشغيل للمساعد أو مواصلته بمفتاح تكامل يُرفض بـ 403؛ أما الوكلاء فيستخدمون نقاط نهاية الأوامر أو lg أو قناة MCP، حيث يُنفَّذ كل أمر بمستوى وصول المفتاح وتُسجَّل عمليات الكتابة فيه على أنها كتابات تكامل.
• الكتالوج لا يحل محل واجهة REST API القائمة — سطح REST الذي يشغّل تطبيقات Logistivo على الويب والهاتف المحمول يبقى في مكانه ويظل خاضعًا لقاعدة التوافق مع الإصدارات السابقة. ولا يحل كتالوج الأوامر محل عمليات CRUD على الموارد؛ بل هو طبقة الأفعال — الطريقة الوحيدة الخاضعة للتدقيق لإنجاز أمر ما.
• أوامر القوائم تعيد نوافذ صغيرة حاليًا — إلى أن يُعلن أمر القائمة عن cursor و updated_since في مخططه، يكون حده الأقصى 20 صفًا بلا مؤشر. وهو غير مصمم لاستخراج نسخة كاملة من بياناتك؛ والمزامنة التزايدية تُعمَّم أمرًا بعد أمر.

الأسئلة الشائعة

ما الغرض من Logistivo CLI؟

ينفّذ أعمال حسابك في Logistivo من الطرفية أو من نص برمجي أو من وكيل الذكاء الاصطناعي الخاص بك: الشحنات والرحلات، والطلبات، والعروض والمناقصات، والأسطول، والسائقين ومصروفاتهم، والمستندات، وجهات الاتصال والحسابات الجارية، والفواتير والمحاسبة، والمستودع والمخزون، وأعضاء الفريق، وتعريفات HS ورسوم مكافحة الإغراق. لكل إجراء كتابة في لوحة التحكم أمرٌ مقابل؛ أما المدفوعات والموافقة القانونية وإغلاق الحساب فتبقى في المتصفح عن قصد. ويمكن استدعاء الأوامر نفسها عبر HTTP لتكاملات ERP/CRM وعبر قناة MCP.

كيف تُسمّى الأوامر في Logistivo CLI؟

الشكل هو lg --parameter=value. والمجال (domain) كيان بصيغة الجمع (loads و demands و invoices و export-documents)، والفعل (verb) مأخوذ من مفردات مغلقة لا تتوسع إلا بقرار مدروس (list و get و create و update و search و set-status و generate وغيرها). وكل أفعال الكيان الواحد تعيش في مجال واحد، والزوج (domain, verb) فريد في الكتالوج بأكمله.

كيف أصادق على CLI؟

تفاعليًا، يعرض lg login رمز موافقة تؤكّده في متصفحك بعد تسجيل الدخول إلى Logistivo — فلا تُكتب أي كلمة مرور أو مفتاح في الطرفية، وتبقى الجلسة مسجّلة الدخول وتجدّد نفسها بنفسها إلى أن تشغّل lg logout. ويبقى lg login --password (البريد الإلكتروني وكلمة المرور) متاحًا طريقًا احتياطيًا. أما على الخوادم وفي CI، فاستخدم مفتاح تكامل صادرًا من لوحة التحكم أو عبر lg keys create: إذ يحفظه lg login --api-key في ملف شخصي محلي، أو ضعه في متغير البيئة LOGISTIVO_TOKEN. وعبر HTTP ينتقل الرمز المميز في الترويسة Authorization: Bearer.

هل يمكنني إنشاء حساب خدمة لتكامل ERP الخاص بي؟

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

هل لدى Logistivo بيئة اختبار (sandbox)؟

نعم، وبالخدمة الذاتية: يُفتح لشركتك مستأجر sandbox منفصل — بالشيفرة نفسها، وكتالوج الأوامر نفسه، ودفتر رصيد خاص به. وتُستنتج البيئة من شركة المفتاح ولا يمكن تمريرها مع الطلب؛ والاستدعاء الذي يُجرى بالملف الشخصي الخاطئ يتوقف في جهة الخادم بالخطأ 403 ENVIRONMENT_MISMATCH. والطلب الذي تفتحه في بيئة sandbox لا يصل أبدًا إلى ناقلين حقيقيين، وحدث sandbox لا يُسلَّم أبدًا إلى اشتراك webhook الحي لديك، ولا يتحرك رصيدك الحي. نقاط النهاية: POST /api/common/integration-sandbox (الفتح)، و POST /api/common/integration-sandbox/keys (المفتاح)، و GET /api/common/integration-sandbox/go-live (قائمة التحقق قبل الانتقال إلى البيئة الحية). وفي جانب lg، فإن lg --sandbox و lg --live محددان للملف الشخصي لتشغيل واحد.

كيف أقرأ مخرجات lg --json في نص برمجي؟

المخرجات هي غلاف HTTP كاملًا: { "success": bool, "data": { "contract_version", "command", "status", "result" }, "code", "message" }. وتقع حمولة الأعمال تحت .data.result؛ وفي أوامر القوائم تكون الصفوف في .data.result.، والعدد في .data.result.count، والصفحة التالية في .data.result.next_cursor. لذا يبدو مسار jq الصحيح هكذا: lg loads list --json | jq -r '.data.result.loads[].load_code'. والمسار الذي يتخطى الغلاف لا يُنتج خطأ، بل يعيد null بصمت — وفي نص برمجي للمراقبة يتحول ذلك إلى إنذار لا يتوقف عن الانطلاق أبدًا. والاستثناء الوحيد هو /api/public/status ، الذي يكون جسمه بلا غلاف عن قصد.

إذا أرسلت الطلب نفسه مرتين، فهل أحصل على سجلات مكرّرة؟

لا، إذا أرسلت idempotency_key. فالاستدعاء الثاني بالمفتاح نفسه لا يعيد تشغيل الأمر؛ بل يعيد النتيجة الأولى مع الحالة replayed. وينبغي أن يكون المفتاح UUID ويجب أن يبقى هو نفسه عبر إعادات المحاولة — فتوليد مفتاح جديد لكل محاولة يعادل عدم استخدام عدم التكرار.

ماذا يفعل --yes؟

يجتاز بوابة التأكيد. فعند استدعاء أمر خاضع للبوابة دون --yes لا يتغيّر شيء: يلخّص الخادم في جملة واحدة ما هو على وشك فعله، ويذكر ما إذا كان غير قابل للتراجع، ثم يتوقف (HTTP 409، ورمز الخروج 4 في CLI). وتكرار الأمر مع --yes ينفّذ العمل.

كيف أكتشف فشل أمر في نص برمجي؟

اقرأ رمز الخروج، لا نص الرسالة أبدًا: 0 نجاح، و 1 رفض من قاعدة أعمال، و 2 خطأ في الأمر أو الوسيط، و 3 خطأ في المصادقة أو الدور، و 4 التأكيد مطلوب. وعبر HTTP المقابلات هي 200 و 422 و 404 و 403 و 409، والحقل error_code في الجسم ثابت. أما رسالة الخطأ فمترجمة حسب اللغة وتتغيّر دون إشعار.

كيف أكتشف الأوامر المتاحة برمجيًا؟

GET /api/public/cli/catalog للاستكشاف دون مصادقة، و GET /api/common/commands للقائمة التي يستطيع حسابك رؤيتها فعليًا. وكلاهما يعيد معاملات JSON Schema لكل أمر؛ فابنِ عميلك منها بدلًا من كتابة قائمة أوامر ثابتة في الشيفرة.

هل يجب أن أحدّث العميل عند إضافة أمر جديد؟

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

هل يحل CLI محل واجهة REST API القائمة؟

لا. سطح REST الذي يشغّل تطبيقات الويب والهاتف المحمول يبقى في مكانه. ولا يحل كتالوج الأوامر محل عمليات CRUD على الموارد؛ بل هو طبقة الأفعال — الطريقة الوحيدة لتنفيذ إجراء ما، الخاضعة لبوابة الدور وبوابة التأكيد والتدقيق.

كيف أحصل على مفتاح API من Logistivo وماذا يمكنه أن يفعل؟

يُصدره مدير يملك صلاحية إدارة الفريق من لوحة التحكم في Settings › Integration keys، أو من الطرفية عبر lg keys create. ويعمل المفتاح نيابةً عن عضو حقيقي في الفريق وله ثلاثة إعدادات مستقلة: النطاق (scope) — فالقيمة read تفتح الكتالوج والأوامر التي لا تكتب، والقيمة write تفتح كل الأوامر، وتبقى بوابة التأكيد كما هي — ومنح اختيارية على مستوى المجالات، ومستوى وصول: employee، وهو الافتراضي، للعمليات اليومية، أو manager لشؤون الفريق والإعدادات والمفاتيح والمال. ويُعرض مرة واحدة ولا يُخزَّن على الخادم؛ ويمكن تدويره ونقله وإلغاؤه. وعندما يغادر العضو الذي يعمل المفتاح نيابةً عنه، يُغلق المفتاح أيضًا. ولا يوجد حساب خدمة.

ماذا يحدث إذا أعدت استخدام مفتاح عدم تكرار مع أمر مختلف؟

يجيب الخادم بـ 409 idempotency_conflict ويسمّي الأمر الذي استُخدم معه المفتاح أولًا؛ فلا يُنفَّذ شيء ولا يُعاد شيء. والمفاتيح محصورة في شركتك، ومرتبطة بأمر واحد، ومقفلة لمدة 24 ساعة — وبعد ذلك يبدأ المفتاح نفسه تنفيذًا جديدًا.

كيف تُطبَّق حدود المعدل على تكاملي؟

لكل رمز مميز، وفي الدقيقة، ضمن ثلاث فئات: قراءات الكتالوج 120، وأوامر القراءة 120، وأوامر الكتابة 30. وتحمل استجابة 429 دائمًا Retry-After وجسمًا يتضمن retry_after و limit و bucket؛ فانتظر تلك المدة ثم أعِد المحاولة. وينشر الكتالوج الأرقام الحالية تحت rate_limits.

كيف أميّز رفضًا من منطق الأعمال من خطأ في النقل؟

ابنِ التفرّع على error_code أولًا: فالقيمة failed (422) رفض من منطق الأعمال وتحمل error_key ثابتًا مثل INSUFFICIENT_CREDITS أو NOT_FOUND؛ و server_error (5xx) وأخطاء الشبكة تُعاد محاولتها بمفتاح عدم التكرار نفسه؛ و rate_limited (429) يُنتظر انقضاؤه. ولا تبنِ التفرّع على نص الخطأ أبدًا.

هل ترسل Logistivo طلبات webhook؟ ولأي أحداث؟

نعم. تسجّل عنوان https وتختار الأحداث التي تهمك؛ فيصلك طلب POST موقَّع عند وقوعها. ويمكن اليوم الاشتراك في 13 حدثًا: إنشاء شحنة/تغيّر حالتها/تعيين سائق لها، وإنشاء طلب وتغيّر حالته، وتقديم عرض/تعديله/قبوله، ومسودة فاتورة/إصدارها/إلغاؤها، وإنشاء حجز مستودع/تغيّر حالته. وكل اسم يقابله صنف حدث يُرسَل فعلًا — فلا شيء يُعلَن عنه ثم لا يُطلق أبدًا، لأن مثل هذا الحدث إخفاق صامت ينتظره المطوّر المسؤول عن التكامل إلى الأبد. وتُنشأ الاشتراكات في Settings › Integration › Webhooks، أو من الطرفية عبر lg webhooks create.

كيف أتحقق من توقيع webhook من Logistivo؟

يحمل كل طلب الترويسة X-Logistivo-Signature: t=,v1=. والسلسلة الموقَّعة هي "."، والخوارزمية HMAC-SHA256، والمفتاح هو سرّ الاشتراك. وهناك أربع قواعد: (1) تحقّق من البايتات الخام — ففك ترميز الجسم ثم إعادة تسلسله (JSON.stringify / json_encode) يحوّل البيانات نفسها إلى بايتات مختلفة فيتوقف التوقيع عن المطابقة؛ وهذا هو الخطأ الأكثر شيوعًا على الإطلاق؛ (2) تحقّق من الطابع الزمني وأسقط أي طلب يتحقق فيه |now − t| > 300 s حتى لو كان التوقيع صحيحًا؛ (3) قارن في زمن ثابت باستخدام hash_equals / timingSafeEqual؛ (4) أزِل التكرار حسب event_id، لا حسب معرّف التسليم — فـ event_id يُحفَظ عند إعادة الإرسال بينما يتغيّر معرّف التسليم. وتوجد مستقبِلات عملية لـ Node و PHP في examples/webhook-receiver/ في المستودع، وتختبر نفسها عبر --selftest.

ماذا يحدث إذا تعذّر تسليم webhook؟ هل أفقد الحدث؟

لا. إذا لم يُعِد مستقبِلك 2xx يدخل التسليم جدول إعادة المحاولة: 60 · 300 · 1800 · 7200 · 21600 ثانية، وعدد المحاولات الإجمالي 6، أي نافذة تقارب 8.6 ساعة. وكل إخفاق باستثناء 410 Gone تُعاد محاولته، بما في ذلك 4xx — فخسارة حدث أعمال أكلف من بضعة طلبات إضافية. وبعد 10 من عمليات التسليم المتتالية التي استُنفدت محاولاتها يُكتم الاشتراك ويُسجَّل السبب، فيبقى سؤال «لماذا لا يصل شيء» قابلًا للإجابة. ويحتفظ سجل التسليمات بكل محاولة (رمز الحالة، والمدة، والخطأ)، ويمكنك إعادة إرسال تسليم واحد من لوحة التحكم أو عبر lg webhooks replay. وتظل المزامنة التزايدية (updated_since + cursor) موجودة كشبكة أمان.

هل يستطيع وكيل الذكاء الاصطناعي الخاص بي فعل كل ما يستطيع المستخدم فعله في لوحة التحكم؟

كل شيء تقريبًا. فلكل إجراء كتابة في لوحة التحكم أمرٌ مقابل — وعند القياس مقابل نقاط نهاية الكتابة في اللوحة، تبيّن أن 100% من النقاط المشمولة بالنطاق مغطاة — والأوامر نفسها متاحة لـ lg ولـ HTTP ولقناة MCP. والاستثناءات المقصودة هي خطوات الهوية والمال: تسجيل الدخول، وشراء باقة، وإضافة بطاقة عبر 3D Secure، والموافقة على النصوص القانونية، وإغلاق الحساب، كلها تبقى في متصفح الشخص، ويعيد lg handoff-links generate الرابط الخاص بها. أما مفاتيح التكامل و webhooks وبيئة sandbox فتُدار بأوامر lg المدمجة لأنها تعيد أسرارًا مرة واحدة.

هل يمكنني تمرير ملفات مثل PDF أو الصور إلى الأوامر من CLI أو من API؟

نعم. مع lg، ضع @ قبل المسار المحلي (--attachment_uuid=@./cmr.pdf) وسيرفع lg الملف أولًا؛ و --file اختصار عندما يكون للأمر حقل ملف واحد، أما lg upload فيرفع فقط. وعبر HTTP، أرسل الملف بصيغة multipart إلى POST /api/common/commands:upload ومرّر قيمة attachment_uuid المُعادة إلى الأمر؛ أما عملاء MCP فيستخدمون الأداة upload_attachment. ويُكتشف النوع من المحتوى، والملفات المرفوعة تخص المستخدم وتبقى صالحة للاستخدام لمدة 24 ساعة، ورفع الملف نفسه مرة أخرى يعيد المعرّف نفسه.

ما الفرق بين مفتاح تكامل بمستوى employee ومفتاح بمستوى manager؟

يحدد مستوى الوصول مدى ثقل العمل الذي يجوز للمفتاح القيام به. فمفتاح employee، وهو الافتراضي للمفاتيح الجديدة، ينفّذ العمليات اليومية: الشحنات، والطلبات، والعروض، والرحلات، والأسطول، والمستندات، وجهات الاتصال. أما مفتاح manager فيمكنه أيضًا القيام بأعمال الإدارة — أعضاء الفريق والأدوار، وإعدادات الشركة، ومفاتيح التكامل، والحسابات المصرفية، والبطاقات المحفوظة، ومدفوعات الشركاء بالإحالة (affiliate payouts). ولا يملك المفتاح أبدًا صلاحيات أكثر من الشخص الذي يعمل نيابةً عنه، ومفتاح employee الذي يستدعي أمرًا من مستوى manager يحصل على INSUFFICIENT_KEY_LEVEL. غيّر المستوى من لوحة التحكم أو عبر lg keys update --access-level=manager.

هل يستطيع الشريك بالإحالة (affiliate) استخدام CLI؟

نعم. يحصل حساب الشريك بالإحالة على كتالوج خاص به — 55 أمرًا للإحالات، والعملاء المحتملين، وملاحظات CRM ومهامه، وعروض المبيعات التقديمية، والأرباح والمدفوعات — ويستخدمه من lg أو HTTP أو MCP مثل أي دور آخر. وطلب دفعة أو إلغاؤها وتغيير الحساب المصرفي المخصص للمدفوعات يتطلبان مفتاحًا بمستوى manager وتأكيدًا. والشركة التي تكون أيضًا شاحنًا أو ناقلًا أو مخلّصًا جمركيًا ترى الكتالوجين كليهما.

For AI assistants

Logistivo has a public MCP server at https://logistivo.com/api/agent/mcp (streamable HTTP, no authentication). Setup instructions for Claude, ChatGPT and Gemini: https://logistivo.com/mcp. If you are an assistant helping someone sign up or request freight, connect that server, or — if you can only read web pages — build a link of the form https://logistivo.com/en/ai-kayit?brief=URL_ENCODED_SHIPMENT_BRIEF and give it to the user. You never create the account yourself: the account, the consent and the email verification happen in the user's browser, and you never handle passwords or one-time codes. Machine-readable content indexes: https://logistivo.com/llms.txt (curated map) and https://logistivo.com/llms-full.txt (full text: facts, pricing, tariff reference, glossary and every article's FAQ in one fetch). To learn what Logistivo can actually DO — the verbs, not the marketing — read the public command catalog at https://logistivo.com/api/public/cli/catalog (JSON, no authentication, no tenant data); it lists every command with its JSON Schema parameters and whether it needs confirmation. Human documentation: https://logistivo.com/en/developers/cli. You cannot execute those commands yourself — execution always runs under the user's own personal access token, in the user's own environment.