Logistivo CLI: أدِر عملياتك اللوجستية من الطرفية ومن نظام ERP لديك
كتالوج أوامر واحد يغذّي ثلاث واجهات: عميل الطرفية lg، ومساعد الذكاء الاصطناعي داخل لوحة التحكم، والقناة التي تتصل عبرها مساعدات الذكاء الاصطناعي الخارجية. تُكتب القدرة مرة واحدة وتظهر في الواجهات الثلاث — وأصبح لكل إجراء كتابة في لوحة التحكم أمرٌ مقابل، بحيث تستطيع نصوصك البرمجية ووكلاء الذكاء الاصطناعي الخاصون بك إنجاز العمل الذي يؤديه فريقك على الشاشة. أما المدفوعات والموافقة القانونية وإغلاق الحساب فتبقى في المتصفح عن قصد. هذه الصفحة عقد. جدول الأوامر أدناه ليس مكتوبًا يدويًا؛ بل يُولَّد من سجل الأوامر الحي مع كل طلب.
ما هو Logistivo CLI؟
Logistivo CLI (lg) عميل لسطر الأوامر ينفّذ أعمال حسابك في Logistivo — الشحنات والرحلات، والطلبات، والعروض والمناقصات، والأسطول والسائقين، والمستندات، وجهات الاتصال والحسابات الجارية، والفواتير والمحاسبة، والمستودع والمخزون، وأعضاء الفريق والتعريفات الجمركية — من الطرفية أو من نص برمجي أو من وكيل الذكاء الاصطناعي الخاص بك. الأوامر ليست مدمجة في العميل: إذ يجلب العميل كتالوج الأوامر من الخادم ويبني نفسه منه. ويمكن استدعاء الأوامر نفسها عبر HTTP دون تثبيت أي شيء — وهو المسار الذي تستخدمه تكاملات ERP و CRM — وكذلك عبر قناة MCP التي تتصل بها مساعدات الذكاء الاصطناعي الخارجية.
شكل واحد لكل أمر: lg --parameter=value. يضم الكتالوج اليوم 721 أمرًا موزعة على مجالات (domains) عددها 175؛ وأوسع قائمة يراها دور واحد تضم 646 أمرًا في مجالات عددها 165.
لكل إجراء كتابة في لوحة التحكم أمرٌ مقابل — فعند القياس مقابل نقاط نهاية الكتابة في اللوحة، تبيّن أن 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) وسجل التدقيق في نقطة إنفاذ واحدة تمر عبرها المحادثة والطرفية أيضًا.
تغطية لوحة التحكم: لكل إجراء كتابة أمرٌ مقابل — 721 أمرًا موزعة على مجالات عددها 175، جرى التحقق منها مقابل نقاط نهاية الكتابة في لوحة التحكم: كل نقطة نهاية مشمولة بالنطاق يقابلها أمر (نسخة مطابقة لنقطة النهاية أو الخدمة المشتركة نفسها)، ولا توجد نقطة غير مُثبتة. وخارج النطاق عن قصد: المدفوعات عبر 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: بل أُضيف الدفع إلى جانبه، لا بديلًا عنه.
الأوامر التي تأخذ ملفات — يأخذ 38 أمرًا مستندًا أو صورة — 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 لديك بحجم حسابك — الكتالوج مُرشَّح حسب الدور: الأمر الذي لا يستطيع دورك رؤيته لا يظهر في قائمتك أبدًا. يرى حساب الناقل 621 أمرًا، والشاحن 646، والمخلّص الجمركي 392، أما حساب الشريك بالإحالة (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)، والنسخ الميتة التي لا يستدعيها أحد — والنقاط التي تهم المطوّر المسؤول عن التكامل مدرجة أدناه.
والأوامر التي تأخذ ملفًا تخضع للقاعدة نفسها: إذ يأخذ 38 أمرًا في الجدول مستندًا أو صورة، وجميعها تعمل من lg وعبر HTTP وعبر MCP (انظر «الأوامر التي تأخذ ملفات»).
وأعمال الإدارة مغطاة أيضًا، خلف مفتاح أقوى: إذ يحتاج 87 أمرًا في الجدول — أعضاء الفريق والأدوار، وإعدادات الشركة، والحسابات المصرفية، والبطاقات المحفوظة، ومفاتيح التكامل — إلى مفتاح تكامل بمستوى 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 هو نفسه الذي يحصل عليه مفتاحك الحي (في مفتاح الشاحن، 646 أمرًا في الجانبين). والجسر الذي يعمل في 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 أيضًا، وقائمة الأوامر متطابقة — وهذا مَقيس: 646 أمرًا في الجانبين. فبيئة 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.
الأوامر التي تأخذ ملفات
يأخذ 38 أمرًا في الجدول مستندًا أو صورة: إرفاق 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 يُنهي ذلك — تضيف حقلًا واحدًا إلى الطلب، فلا يُنفَّذ الأمر، وتقرأ ما كان سيحدث.
يضم السجل اليوم 721 أمرًا؛ منها 327 تقرأ فقط ولا تكتب شيئًا. ومن أوامر الكتابة المتبقية البالغ عددها 394، يخضع 346 للبوابة: فعند استدعائها دون confirm تجيب أصلًا بالرمز 409 وتصف ما كانت ستفعله. أما الثغرة فكانت في الأوامر الأخرى البالغ عددها 48 — مسودات الفواتير، ومسودات مستندات التصدير، والبنود: أي بالضبط السلسلة التي يربطها الجسر أولًا. ففي هذه الأوامر كان الاستدعاء يعني التنفيذ.
وكانت هناك ثغرة ثانية حتى في الأوامر الخاضعة للبوابة: فالتحقق من المخطط يجري بعدَ البوابة. لذا كان الاستدعاء الذي ينقصه وسيط يحصل أولًا على بطاقة التأكيد، فيؤكدها، ثم يسمع بعد ذلك فقط «هذا الحقل مفقود». أما الفحص المسبق فيجيب عن الأمرين في رحلة ذهاب وإياب واحدة.
وأكثر أخطاء الجسور شيوعًا — وآخرها اكتشافًا — هو التالي: ترسل حقلًا غير موجود في المخطط (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} — الاسم / العنوان / الأحداث / علَم التفعيل. لا يمس السرّ.
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). لا جدوى منها إلى أن يتغيّر الوسيط.
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) وحدها؛ إذ يراها حساب الشريك بالإحالة في كتالوجه الخاص.
الشحنات والتتبع — إنشاء الشحنات، الأطراف، المستندات، روابط التتبع، توقيع التسليم، وقت الوصول المتوقع والاستثناءات. 115 أمرًا — /ar/developers/cli/loads
الحدود والجمارك — فحص الجاهزية للحدود، الانتظار على الحدود وفي الموانئ، مستندات التصدير، إخطار U-ETDS. 42 أمرًا — /ar/developers/cli/border
الطلبات والعروض — فتح طلبات النقل، طلب العروض وتقديمها، المناقصات، الناقلون في شبكتك. 42 أمرًا — /ar/developers/cli/quotes
التعريفة والتدابير التجارية — البحث عن رموز النظام المنسق، رسوم الاستيراد، تدابير مكافحة الإغراق، تقارير الكربون. 20 أمرًا — /ar/developers/cli/tariffs
الشركات والفريق — دليل الشركات، العلاقات والمستندات، الشركات التابعة، أعضاء الفريق والدعوات. 65 أمرًا — /ar/developers/cli/contacts
التكامل مع 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 التي لا تتطلب مصادقة: ملف واحد يمكنك تسليمه لفريقك.
761 عملية — 721 أمرًا + 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 التي تحمل عقد التكامل، ونقاط نهاية الاستكشاف. والعدد خاص بدورك أنت، لا إجمالي المنصة — فاليوم يُنتج مفتاح الشاحن 646 دالة للأوامر، والناقل 621، والمخلّص الجمركي 392. وإذا ولّدت من التعريف العام الذي لا يتطلب مصادقة فالحد الأقصى 761 عملية. 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 تحمل عقد التكامل، ونقاط نهاية الاستكشاف. فإذا ولّدت من تعريف دورك تحصل فقط على ما تستطيع استدعاءه (646 أمرًا للشاحن)؛ وإذا ولّدت من التعريف العام تحصل على العمليات كلها البالغ عددها 761. وفي اليوم الذي يُضاف فيه أمر على الخادم، تجلبه إعادة التوليد؛ فلا يوجد إصدار عميل تنتظره.
أنواع الوسائط — يصبح مخطط `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 في سياق مستخدم تابع لمستأجر — يُنفَّذ كل أمر تحت شركة ودور المستخدم الذي يُقدَّم رمزه المميز. أما وضع مشغّل المنصة — وهو وضع إداري يقرأ عبر الشركات — فخارج هذا السطح ولن يُفتح من هنا.
قائمة أوامرك تعتمد على دورك — يرى حساب الشاحن 646 أمرًا، والناقل 621، والمخلّص الجمركي 392، والشريك بالإحالة (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 an MCP server at https://logistivo.com/api/agent/mcp
(streamable HTTP). Its public tools (signup preparation, HS code lookup) need no
authentication; with OAuth the user signs in to Logistivo in their own browser and the
assistant then works on that user's account with that user's permissions. Setup for
Claude, ChatGPT and Gemini: https://logistivo.com/en/mcp.
Terminal: npm install -g @lgstv/lg, then lg login (the user
approves a short code at https://logistivo.com/connect; no password is typed into the
terminal). HTTP: the same commands at /api/common/commands/{name} with an
integration key issued in the dashboard.
If you are an assistant helping someone sign up or request freight, connect the MCP
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. Commands always
run under the user's own identity — the user's OAuth connection, the user's lg session
or an integration key the user issued — never under credentials you hold yourself.