Logistivo CLI: अपना लॉजिस्टिक्स संचालन टर्मिनल से और अपने ERP से चलाएँ
एक ही कमांड कैटलॉग तीन सतहों को चलाता है: lg टर्मिनल क्लाइंट, डैशबोर्ड के भीतर का AI सहायक, और वह चैनल जिससे बाहरी AI सहायक जुड़ते हैं। कोई क्षमता एक बार लिखी जाती है और तीनों में दिखाई देती है — और अब पैनल की हर लिखने वाली कार्रवाई के लिए एक कमांड है, इसलिए आपकी स्क्रिप्ट और आपके अपने AI एजेंट वह काम कर सकते हैं जो आपकी टीम स्क्रीन पर करती है। भुगतान, कानूनी सहमति और खाता बंद करना जानबूझकर ब्राउज़र में ही रखे गए हैं। यह पृष्ठ एक कॉन्ट्रैक्ट है। नीचे दी गई कमांड तालिका हाथ से नहीं लिखी गई है; यह हर अनुरोध पर लाइव कमांड रजिस्ट्री से जनरेट होती है।
Logistivo CLI क्या है?
Logistivo CLI (lg) एक कमांड लाइन क्लाइंट है जो आपके Logistivo खाते का काम — लोड और ट्रिप, डिमांड (माल ढुलाई अनुरोध), बोलियाँ और टेंडर, फ़्लीट और ड्राइवर, दस्तावेज़, संपर्क और चालू खाते, इनवॉइस और लेखांकन, गोदाम और स्टॉक, टीम सदस्य और सीमा शुल्क टैरिफ़ — टर्मिनल, स्क्रिप्ट या आपके अपने AI एजेंट से चलाता है। कमांड क्लाइंट में पहले से गढ़ी हुई नहीं होतीं: क्लाइंट सर्वर से कमांड कैटलॉग खींचता है और उसी से अपना रूप बनाता है। यही कमांड बिना कुछ इंस्टॉल किए HTTP पर भी बुलाई जा सकती हैं — ERP और CRM इंटीग्रेशन यही रास्ता अपनाते हैं — और उस MCP चैनल के ज़रिए भी, जिससे बाहरी AI सहायक जुड़ते हैं।
सभी कमांड का एक ही आकार है: lg --parameter=value; आज कैटलॉग में 175 डोमेन में 721 कमांड हैं; किसी एक भूमिका को दिखने वाली सबसे बड़ी सूची 165 डोमेन में 646 कमांड की है।
पैनल की हर लिखने वाली कार्रवाई के लिए एक कमांड है — पैनल के लिखने वाले एंडपॉइंट से मापने पर, दायरे में आने वाले 100% एंडपॉइंट कवर हैं। भुगतान (3D Secure), कानूनी सहमति और खाता बंद करना जानबूझकर ब्राउज़र में ही रहते हैं; इनके लिए कमांड इसके बजाय एक लिंक लौटाती है।
जो कमांड कोई दस्तावेज़ या फ़ोटो लेती हैं, वे ब्राउज़र के बाहर भी काम करती हैं: --attachment_uuid=@./cmr.pdf लिखें और lg पहले फ़ाइल अपलोड करता है; HTTP पर आप /api/common/commands:upload पर अपलोड करते हैं और लौटाया गया attachment_uuid पास करते हैं।
इंटीग्रेशन कुंजियों का एक एक्सेस स्तर होता है: रोज़मर्रा के संचालन के लिए employee (नई कुंजियों का डिफ़ॉल्ट), और टीम, सेटिंग्स, कुंजियों तथा पैसे के लिए manager। कोई कुंजी कभी भी उस व्यक्ति से अधिक अधिकार नहीं रखती जिसकी ओर से वह काम करती है।
फ़्लैग कभी गढ़े नहीं जाते: हर फ़्लैग कमांड के अपने JSON Schema का एक पैरामीटर नाम है, और उसका प्रकार तथा वह अनिवार्य है या नहीं — ये भी वहीं से आते हैं।
लिखने वाली कमांड पुष्टि माँगती हैं; अपरिवर्तनीय कमांड पुष्टि के बिना कभी नहीं चलतीं (HTTP 409, CLI एग्ज़िट कोड 4)।
दोबारा प्रयास करने से डुप्लिकेट नहीं बनते: idempotency_key वाली कॉल अधिकतम एक बार चलती है।
हर निष्पादन एक ही ऑडिट लेजर में दर्ज होता है — वह टर्मिनल से आया, चैट से या किसी सहायक से, यह रिकॉर्ड में रहता है।
आज क्या लाइव है, और क्या आने वाला है
यह खंड जानबूझकर पृष्ठ के शीर्ष पर रखा गया है। किसी इंटीग्रेशन दस्तावेज़ की सबसे महँगी गलती यह है कि वह किसी ऐसे एंडपॉइंट का वर्णन करे जो अभी खुला नहीं है, मानो वह खुल चुका हो: इंटीग्रेटर कोड लिखता है, एंडपॉइंट 404 लौटाता है, और भरोसा फिर वापस नहीं आता।
क्योंकि कॉन्ट्रैक्ट स्थिर है, आज आप जो इंटीग्रेशन कोड लिखते हैं वह शेष हिस्सों के खुलने पर भी काम करता रहता है। जिन फ़ील्ड को आप नहीं जानते, उन्हें अनदेखा करना अनिवार्य है; यही नियम हमें बिना कुछ तोड़े नई चीज़ें जोड़ने देता है।
कमांड कैटलॉग और पहचान तालिका — हर कमांड की सार्वजनिक domain/verb पहचान स्थिर (फ़्रीज़) है और कॉन्ट्रैक्ट संस्करण हर कैटलॉग प्रतिक्रिया में और X-Contract-Version हेडर में 1 के रूप में प्रकाशित होता है। इस पृष्ठ की तालिका लाइव रजिस्ट्री से जनरेट होती है: सर्वर पर जोड़ी गई कमांड यहाँ अपने आप दिखाई देती है, और हटाई गई कमांड गायब हो जाती है।
बिना प्रमाणीकरण वाला खोज (डिस्कवरी) एंडपॉइंट — GET /api/public/cli/catalog — कमांड नाम, domain/verb पहचान, विवरण, JSON Schema पैरामीटर, गेट फ़्लैग और संस्करण फ़ील्ड (since, deprecated_at, replaced_by, aliases)। कोई प्रमाणीकरण नहीं: टोकन बनाना वह कदम है जो इंटीग्रेशन के निर्णय के बाद आता है, उससे पहले नहीं। प्रतिक्रिया में किसी भी टेनेंट का कोई डेटा नहीं होता।
प्रमाणीकृत कैटलॉग और निष्पादन एंडपॉइंट — GET /api/common/commands, GET /api/common/commands/{name} और POST /api/common/commands/{name} एंडपॉइंट। भूमिका गेट, पुष्टि गेट, आइडेम्पोटेंसी और ऑडिट लेजर एक ही प्रवर्तन बिंदु पर रहते हैं, जिससे चैट और टर्मिनल भी होकर गुज़रते हैं।
पैनल कवरेज: हर लिखने वाली कार्रवाई के लिए एक कमांड — 175 डोमेन में 721 कमांड, जिन्हें पैनल के लिखने वाले एंडपॉइंट से मिलाकर जाँचा गया है: दायरे में आने वाला हर एंडपॉइंट किसी कमांड से समर्थित है (एंडपॉइंट का प्रतिबिंब या वही साझा सर्विस), और कोई भी अप्रमाणित नहीं है। जानबूझकर दायरे से बाहर: 3D Secure वाले भुगतान, कानूनी सहमति, खाता बंद करना और साइन-इन, जो ब्राउज़र में रहते हैं; कुंजी, वेबहुक और सैंडबॉक्स प्रबंधन, जो lg की बिल्ट-इन कमांड हैं; और ड्राइवर ऐप के अपने एंडपॉइंट।
प्रीफ़्लाइट (dry_run): चलाए बिना देखें — अनुरोध बॉडी में dry_run: true होने पर कमांड नहीं चलती: वैलिडेशन, भूमिका/स्कोप गेट, लक्ष्य का निर्धारण और क्रेडिट गणना — सब निष्पादित होते हैं और एक पूर्वावलोकन लौटता है; कुछ भी लिखा नहीं जाता, कोई क्रेडिट खर्च नहीं होता और आइडेम्पोटेंसी कुंजी उपयोग में नहीं आती। बैच एंडपॉइंट भी इसे लेता है, प्रति बैच। प्रीफ़्लाइट कभी कमांड के हैंडलर में प्रवेश नहीं करता; जब यह सुविधा जारी हुई, तब उस समय कैटलॉग की हर लिखने वाली कमांड पर किए गए 178 प्रीफ़्लाइट ने एक भी लेखन (write) स्टेटमेंट नहीं बनाया।
इंटीग्रेशन कुंजियाँ — API कुंजियाँ जो किसी वास्तविक टीम सदस्य की ओर से काम करती हैं, पैनल में या lg keys create से जारी की जाती हैं: read/write स्कोप, एक्सेस स्तर (डिफ़ॉल्ट रूप से employee, या manager), जीवनकाल, अंतिम उपयोग, रोटेट, ट्रांसफ़र और रद्द (revoke)। lg login --api-key, lg whoami और सर्वर की ओर से कुंजी रद्द करने वाला lg logout इन्हीं पर बने हैं।
सैंडबॉक्स — प्रोडक्शन को छुए बिना लिखने का अभ्यास करें — हर कंपनी के लिए एक अलग सैंडबॉक्स टेनेंट, उसी कमांड कैटलॉग के साथ; इसे स्वयं-सेवा से खोला जाता है और यह अपनी कुंजी जारी करता है। क्रेडिट, मार्केटप्लेस और वेबहुक रूटिंग दोनों वातावरणों के बीच अलग-अलग हैं; वातावरण कुंजी की कंपनी से निकाला जाता है और अनुरोध के साथ नहीं भेजा जा सकता।
संस्करण प्रबंधन, त्रुटि वर्गीकरण, आइडेम्पोटेंसी और रेट लिमिट — कमांड since / deprecated_at / replaced_by / aliases रखती हैं और अप्रचलित (deprecated) कमांड X-Deprecated हेडर के साथ उत्तर देती है। व्यावसायिक विफलताएँ ट्रांसपोर्ट-स्तर के error_code के साथ एक स्थिर error_key भी रखती हैं, और कुंजियों का शब्दकोश कैटलॉग में प्रकाशित है। आइडेम्पोटेंसी कुंजियाँ आपकी कंपनी तक सीमित हैं, एक कमांड से बँधी हैं और 24 घंटे के लिए लॉक रहती हैं। रेट लिमिट प्रति टोकन हैं, तीन बकेट में, और हर 429 के साथ Retry-After आता है।
आउटगोइंग वेबहुक: कुछ होने पर एक POST — हस्ताक्षरित पुश 13 इवेंट के लिए लाइव है। सब्सक्रिप्शन पैनल से या lg webhooks से प्रबंधित होते हैं; हस्ताक्षर अपना टाइमस्टैम्प साथ रखता है, पुनः प्रयास का शेड्यूल 60 · 300 · 1800 · 7200 · 21600 सेकंड है और म्यूट करने का कारण हमेशा दर्ज किया जाता है। हर इवेंट नाम के पीछे एक इवेंट क्लास है जो वास्तव में डिस्पैच होती है — ऐसा कुछ नहीं है जिसकी घोषणा की गई हो और जो फिर कभी भेजा न गया हो। पुल रेल (updated_since + cursor) हटाई नहीं गई: पुश उसके साथ जोड़ा गया, उसकी जगह नहीं।
फ़ाइलें लेने वाली कमांड — 38 कमांड कोई दस्तावेज़ या फ़ोटो लेती हैं — CMR, इनवॉइस, वाहन पंजीकरण, पैलेट की फ़ोटो। 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` के ज़रिए बिना इंस्टॉल किए चलाएँ। यह एक ही फ़ाइल है जिसकी कोई निर्भरता (dependency) नहीं है, और क्योंकि HTTP सतह खुली है, आप इसके बिना भी इंटीग्रेट कर सकते हैं। यह एक अनुमोदन कोड से साइन इन करता है जिसकी पुष्टि आप ब्राउज़र में करते हैं, और फिर अपने सत्र को स्वयं नवीनीकृत करते हुए साइन इन बना रहता है; यह आपके लिए स्थानीय फ़ाइलें अपलोड करता है (@path, --file, lg upload), इंटीग्रेशन कुंजियाँ प्रबंधित करता है (lg keys), कभी भी कमांड लाइन पर कोई सीक्रेट नहीं लेता, Retry-After का पालन करता है, 5xx पर उसी आइडेम्पोटेंसी कुंजी के साथ पुनः प्रयास करता है और अप्रचलित कमांड तथा नए कॉन्ट्रैक्ट संस्करणों पर चेतावनी देता है।
इंक्रीमेंटल सिंक: कर्सर पेजिनेशन और updated_since — नीचे दिया गया कॉन्ट्रैक्ट (limit + अपारदर्शी हस्ताक्षरित कर्सर, next_cursor, updated_since) तय है और सूची कमांड में चरणबद्ध रूप से लागू किया जा रहा है। जब तक कोई सूची कमांड अपने JSON Schema में cursor और updated_since घोषित नहीं करती, उसे एक छोटी विंडो मानें: अधिकतम 20 पंक्तियाँ, कोई कर्सर नहीं।
इसे क्या अलग बनाता है: क्लाइंट कोई कमांड नहीं जानता, वह उन्हें रचता है
यही वह एक निर्णय है जो इस पृष्ठ के बाकी हिस्से को सार्थक बनाता है। किसी सामान्य CLI में कमांड क्लाइंट के भीतर रहती हैं; Logistivo में वे सर्वर पर रहती हैं।
पारंपरिक व्यवस्था में, जब सर्वर को कोई नई क्षमता मिलती है, तो क्लाइंट की नई रिलीज़ चाहिए होती है और उपयोगकर्ता को उसे इंस्टॉल करना पड़ता है। इस बीच दोनों पक्ष अलग-अलग बातें जानते हैं — और इंटीग्रेशन में यही सबसे चुपचाप होने वाली विफलता है: स्क्रिप्ट चलती है, एग्ज़िट कोड 0 होता है, और कमांड बस वह वर्णन नहीं करती जो सर्वर कर सकता है।
Logistivo में किसी कमांड की परिभाषा एक ही रिकॉर्ड है: उसका नाम, वह क्या करती है, उसके JSON Schema पैरामीटर, कौन-सी भूमिकाएँ उसे देख सकती हैं, क्या उसे पुष्टि चाहिए और क्या उसका प्रभाव पलटा जा सकता है। जब lg शुरू होता है, तो वह यह कैटलॉग खींचता है और उसी से अपना सहायता पाठ, अपने फ़्लैग और अपना इनपुट वैलिडेशन जनरेट करता है। जिस क्षण सर्वर पर कोई कमांड जोड़ी जाती है, lg उसे जान लेता है — बिना किसी क्लाइंट अपडेट के।
यही कैटलॉग डैशबोर्ड के AI सहायक को और उस चैनल को भी चलाता है जिससे बाहरी AI सहायक जुड़ते हैं। कोई क्षमता एक बार लिखी जाती है और तीन जगह दिखाई देती है — और तीनों एक ही भूमिका गेट, एक ही पुष्टि गेट और एक ही ऑडिट लेजर से होकर गुज़रती हैं। CLI कमांड की कोई अलग सूची नहीं है; यदि होती, तो छह महीनों के भीतर तीनों सतहें चुपचाप एक-दूसरे से अलग हो जातीं।
कोई संस्करण भटकाव नहीं — क्लाइंट जो कमांड सूची जानता है, वह अपनी बनावट से ही वही सूची है जो सर्वर के पास है। "किस lg संस्करण में यह कमांड है?" — ऐसा कोई प्रश्न होता ही नहीं।
फ़्लैग नामों का कभी अनुमान नहीं लगाया जाता — किसी कमांड के फ़्लैग ठीक वही होते हैं जो उसके JSON Schema में पैरामीटर नाम हैं। कोई कमांड क्या स्वीकार करती है, यह जानने का तरीका कोई दस्तावेज़ पढ़ना नहीं, बल्कि कैटलॉग पढ़ना है — और कैटलॉग हमेशा अद्यतन रहता है।
आपका CLI उतना ही बड़ा है जितना आपका खाता — कैटलॉग भूमिका के अनुसार फ़िल्टर होता है: जो कमांड आपकी भूमिका नहीं देख सकती, वह आपकी सूची में कभी नहीं आती। एक कैरियर (ट्रांसपोर्टर) खाता 621 कमांड देखता है, एक शिपर 646, एक कस्टम्स ब्रोकर 392, और एक एफ़िलिएट (रेफ़रल पार्टनर) खाता अपना अलग सेट — 55 कमांड।
दस्तावेज़ीकरण पीछे नहीं छूट सकता — इस पृष्ठ की कमांड तालिका उसी रजिस्ट्री से आती है। कहीं भी ऐसी कोई सूची नहीं है जिसे किसी व्यक्ति को वास्तविकता के साथ मिलाकर रखना पड़े।
नामकरण नियम — कमांड नाम कैसे बढ़ते हैं
कैटलॉग बढ़ेगा। नई कमांड के नाम मनमाने ढंग से नहीं रखे जाते; छह नियम लागू होते हैं। हम उन्हें यहाँ प्रकाशित करते हैं क्योंकि यही वे नाम हैं जिन्हें आपका इंटीग्रेशन वर्षों तक लिखेगा, और उनकी पूर्वानुमेयता आपके लिए मूल्यवान है।
डोमेन एक बहुवचन इकाई है — 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 नहीं कर सकते, तो वह डोमेन नहीं है।
दायरा सीमित करना एक फ़्लैग है, नई क्रिया नहीं — lg fleet-documents list --days=30 सही है; कोई अलग "list-expiring" क्रिया नहीं है, क्योंकि विंडो पहले से ही एक पैरामीटर है। विशेषित (qualified) क्रिया का उपयोग केवल तब होता है जब उसकी लौटाई गई पंक्तियाँ डोमेन की इकाई न हों: loads list-problems समस्या फ़्लैग लौटाती है, लोड नहीं।
(domain, verb) जोड़ी पूरे कैटलॉग में अद्वितीय है — उन दो कमांड के लिए भी जिनकी भूमिकाएँ कभी एक-दूसरे पर नहीं पड़तीं। यदि एक ही जोड़ी दो कमांड को दी जाती, तो आपका इंटीग्रेशन कोड एक नाम देख रहा होता, जबकि CLI इस आधार पर अलग-अलग चीज़ें चलाता कि उसे किसने बुलाया।
कवरेज: पैनल का सब कुछ, एक कमांड से
कई टीमें Logistivo को अपने AI एजेंट या ऑटोमेशन हार्नेस से जोड़ती हैं, और एजेंट तभी उपयोगी है जब वह काम पूरा कर सके। इसलिए नियम सरल है: ऑफ़िस उपयोगकर्ता पैनल में जो कुछ भी बदल सकता है, उसे एक कमांड भी बदल सकती है — उसी भूमिका गेट, उसी पुष्टि गेट और उसी ऑडिट लेजर के पीछे।
यह मापा गया है, केवल दावा नहीं किया गया। पैनल के पीछे का हर लिखने वाला एंडपॉइंट कमांड रजिस्ट्री से मिलाकर जाँचा जाता है, और कोई एंडपॉइंट तभी कवर माना जाता है जब कोई कमांड उसे अपने HTTP प्रतिबिंब के रूप में घोषित करे या वही साझा सर्विस बुलाए। दायरे में आने वाले लिखने वाले एंडपॉइंट में से 100% कवर हैं और कोई भी अप्रमाणित नहीं है। बाहर छोड़ा गया हर एंडपॉइंट एक लिखित कारण रखता है — पहचान और भुगतान के चरण, इंटीग्रेशन कंट्रोल प्लेन, ड्राइवर ऐप के अपने एंडपॉइंट, क्लाइंट टेलीमेट्री, बिना किसी कॉलर वाली मृत प्रतियाँ — और जो किसी इंटीग्रेटर के लिए मायने रखते हैं, वे नीचे सूचीबद्ध हैं।
फ़ाइल लेने वाली कमांड भी इसी नियम के अंतर्गत आती हैं: तालिका में 38 कमांड कोई दस्तावेज़ या फ़ोटो लेती हैं, और वे सभी lg से, HTTP पर और MCP पर काम करती हैं ("फ़ाइलें लेने वाली कमांड" देखें)।
प्रबंधन का काम भी कवर है, एक मज़बूत कुंजी के पीछे: तालिका में 87 कमांड — टीम सदस्य और भूमिकाएँ, कंपनी सेटिंग्स, बैंक खाते, सहेजे गए कार्ड, इंटीग्रेशन कुंजियाँ — को manager-स्तर की इंटीग्रेशन कुंजी चाहिए। employee-स्तर की कुंजी, जो डिफ़ॉल्ट है, रोज़मर्रा का संचालन चलाती है और इन कमांड पर INSUFFICIENT_KEY_LEVEL के साथ अस्वीकार कर दी जाती है।
एफ़िलिएट (रेफ़रल पार्टनर) खातों का अपना अलग कैटलॉग है: 20 डोमेन में 55 कमांड — रेफ़रल, लीड, 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 दिखाता है कि खाता बंद करने का क्या अर्थ होगा, बिना उसे किए।
इंटीग्रेशन कुंजियाँ, वेबहुक और सैंडबॉक्स — इन्हें प्रबंधित करने पर ऐसे सीक्रेट लौटते हैं जिन्हें आपके टर्मिनल में केवल एक बार दिखाया जाना चाहिए, इसलिए ये कैटलॉग कमांड के बजाय अपने HTTP एंडपॉइंट पर चलने वाली lg की बिल्ट-इन कमांड (lg keys, lg webhooks, lg sandbox) हैं। कैटलॉग में केवल दो सीक्रेट-मुक्त कुंजी कमांड हैं: integration-keys list और integration-keys revoke।
डैशबोर्ड सहायक चैट — इंटीग्रेशन कुंजियाँ डैशबोर्ड के भीतर की AI सहायक चैट नहीं चला सकतीं; कुंजी से रन शुरू करने या जारी रखने पर 403 उत्तर मिलता है। इसके बजाय एजेंट कमांड एंडपॉइंट, lg या MCP चैनल से जुड़ता है — वहाँ हर कमांड कुंजी के एक्सेस स्तर पर चलती है और उसके लेखन इंटीग्रेशन लेखन के रूप में दर्ज होते हैं।
ड्राइवर ऐप — ड्राइवर खातों का कोई कमांड कैटलॉग नहीं है, और ड्राइवर ऐप अपने अलग एंडपॉइंट रखता है। ऑफ़िस उपयोगकर्ता ड्राइवरों, उनके दस्तावेज़ों, खर्चों और ट्रिप को कमांड के ज़रिए प्रबंधित करते हैं।
इंस्टॉलेशन और पहचान
lg एक ही फ़ाइल वाली, बिना किसी निर्भरता (dependency) वाली Node स्क्रिप्ट है (Node 18+), जो npm पर @lgstv/lg के नाम से प्रकाशित है। पैकेज दो एक जैसी कमांड इंस्टॉल करता है, lg और logistivo — यदि आपकी मशीन पर lg पहले से किसी alias के रूप में मौजूद है, तो logistivo का उपयोग करें। क्योंकि यह एक ही फ़ाइल है, lg.mjs को किसी ग्राहक के ERP सर्वर पर कॉपी कर देना भी काम करता है। ERP/CRM इंटीग्रेशन बनाने के लिए आपको क्लाइंट की आवश्यकता नहीं है — वही कमांड HTTP पर उपलब्ध हैं।
1. इंस्टॉल करें — आपको केवल Node 18 या उससे नया संस्करण चाहिए; कोई अन्य निर्भरता नहीं है। इसे ग्लोबल रूप से इंस्टॉल करें या npx के ज़रिए बिना इंस्टॉल किए चलाएँ।
2. अनुमोदन कोड से साइन इन करें — lg login एक छोटा अनुमोदन कोड दिखाता है और आपके ब्राउज़र में logistivo.com/connect खोलता है; SSH पर, CI में या --no-browser के साथ यह केवल पता प्रिंट करता है, जिसे आप किसी भी डिवाइस पर, अपने फ़ोन पर भी, खोल सकते हैं। वहाँ हमेशा की तरह साइन इन करें, जाँचें कि पेज पर दिखा कोड वही है जो आपके टर्मिनल में है, केवल पढ़ने की या पढ़ने और कार्रवाई करने की पहुँच चुनें और अनुमोदित करें। टर्मिनल में कुछ भी गोपनीय टाइप नहीं किया जाता: न पासवर्ड, न कुंजी, न वन-टाइम कोड। इसके बाद सत्र उस कंप्यूटर पर साइन इन बना रहता है — टर्मिनल बंद करने से आप साइन आउट नहीं होते, और lg एक्सेस टोकन की अवधि समाप्त होने से पहले उसे स्वयं नवीनीकृत कर देता है। lg logout सर्वर पर भी सत्र समाप्त करता है, और आप इसे पैनल में Settings › Integration keys › AI and CLI connections के अंतर्गत हटा भी सकते हैं। lg login --password (ईमेल और पासवर्ड) एक वैकल्पिक (fallback) तरीके के रूप में उपलब्ध रहता है। इसके लिए 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) में यह केवल स्थानीय (LOCAL) प्रति हटाता है और यह बात स्पष्ट रूप से बताता है। ऑडिट लेजर आपके आर्गुमेंट संग्रहीत करता है, लेकिन जिस भी फ़ील्ड के नाम में token, password, IBAN, card या OTP हो, उसे *** के रूप में छिपा देता है, और उस हर पैरामीटर को भी जिसे कोई कमांड गोपनीय (secret) घोषित करती है।
LOGISTIVO_TOKEN — व्यक्तिगत एक्सेस टोकन। सेट होने पर कॉन्फ़िग फ़ाइल कभी नहीं पढ़ी जाती — CI और सर्वर पर यही पसंदीदा तरीका है।
LOGISTIVO_BASE_URL — सर्वर रूट। डिफ़ॉल्ट https://logistivo.com है। इसे केवल तभी बदलें जब आप अपने स्वयं के वातावरण की ओर इशारा कर रहे हों; --base-url फ़्लैग किसी एक कमांड के लिए यही करता है।
LOGISTIVO_HOME — कॉन्फ़िग फ़ाइल और कैटलॉग कैश की डायरेक्टरी। डिफ़ॉल्ट ~/.logistivo है। यदि आप एक ही मशीन पर दो खातों के साथ काम करते हैं, तो इसे अलग रखें।
LOGISTIVO_PROFILE — किस प्रोफ़ाइल के रूप में चलाना है। `lg profile use` स्थायी चुनाव है; यह वेरिएबल एक बार चलाने के लिए है और CI में लाइव और सैंडबॉक्स प्रोफ़ाइल के बीच स्विच करने का सबसे छोटा तरीका है। अज्ञात प्रोफ़ाइल नाम चुपचाप अनदेखा नहीं किया जाता — वह त्रुटि देता है।
NO_COLOR — सेट होने पर कोई ANSI रंग प्रिंट नहीं होता (`--no-color` फ़्लैग का स्थायी रूप)। इसे उस ब्रिज के लिए चालू करें जो लॉग फ़ाइल या CI आउटपुट में लिखता है; रंग के एस्केप सीक्वेंस उन टूल को तोड़ देते हैं जो बाद में उन लॉग को पढ़ते हैं।
क्लाइंट की सुविधाएँ
ये सुविधाएँ `lg` क्लाइंट के रोज़मर्रा के उपयोग को आसान बनाती हैं। इनमें से कोई भी HTTP कॉन्ट्रैक्ट को नहीं बदलती — यदि आप सीधे HTTP पर इंटीग्रेट करते हैं, तो इस खंड को छोड़ दें।
कई वातावरण और कुंजियाँ — स्टेजिंग और प्रोडक्शन को, या अपने ग्राहक और कैरियर ब्रिज को, अलग-अलग प्रोफ़ाइल में रखें। प्रोफ़ाइल सूची कभी टोकन प्रिंट नहीं करती; हर पंक्ति टोकन का sha256 फ़िंगरप्रिंट दिखाती है। कमांड कैटलॉग प्रति प्रोफ़ाइल, होस्ट और टोकन कैश होता है, इसलिए दो भूमिकाएँ कभी एक-दूसरे की कमांड सूची नहीं देख सकतीं।
इंक्रीमेंटल सिंक: lg sync — कुकबुक वाला सिंक लूप एक ही कमांड में चलाता है: प्रति इकाई वॉटरमार्क, कर्सर के साथ updated_since, JSONL आउटपुट और पाँच मिनट का सुरक्षा मार्जिन। पहले बैकफ़िल के लिए --full का उपयोग करें। यह कमांड केवल पढ़ती है; कोई --write फ़्लैग नहीं है। lg sync --list कैटलॉग से आपकी भूमिका के लिए सिंक की जा सकने वाली इकाइयाँ निकालता है।
त्रुटि अनुभव और शेल कम्प्लीशन — 422 पर क्लाइंट अस्वीकृत फ़ील्ड का नाम उसी फ़्लैग के रूप में बताता है जो आपने टाइप किया था, साथ में स्थिर error_key और कैटलॉग में दी गई उसकी अपनी व्याख्या भी। 409 पर यह तैयार --yes कमांड लाइन प्रिंट करता है; 429 पर यह Retry-After पूरा होने तक प्रतीक्षा करता है। शेल कम्प्लीशन डोमेन, क्रियाएँ, फ़्लैग और enum मान कवर करता है, और ऑफ़लाइन काम करता है।
गोपनीय पैरामीटर कभी कमांड लाइन पर नहीं जाते — कुछ कमांड कोई गोपनीय मान (secret) लेती हैं — उदाहरण के लिए, Paraşüt लेखांकन इंटीग्रेशन को जोड़ने के लिए उस सिस्टम के क्लाइंट क्रेडेंशियल और पासवर्ड चाहिए। lg ऐसा मान कभी फ़्लैग के रूप में स्वीकार नहीं करता, क्योंकि वह आपकी शेल हिस्ट्री और ps आउटपुट में पहुँच जाता: वह इसे स्क्रीन पर दिखाए बिना (बिना echo के) पूछता है, या ---file=PATH से या stdin (---file=-) से पढ़ता है, और इसे केवल मेमोरी में रखता है। जिस कमांड का अनिवार्य पैरामीटर गोपनीय है, वह केवल lg से चलती है: चैट से, MCP पर या lg batch के भीतर बुलाए जाने पर वह SECRET_REQUIRES_CLI के साथ अस्वीकार कर दी जाती है। ऑडिट लेजर मान को हमेशा *** के रूप में दर्ज करता है।
API कुंजी से कनेक्ट करना
कोई ERP, CRM, स्क्रिप्ट या AI एजेंट पैनल में या lg keys create से जारी इंटीग्रेशन कुंजी के साथ Logistivo से जुड़ता है। कुंजी किसी वास्तविक टीम सदस्य की ओर से काम करती है: उस व्यक्ति की भूमिका कमांड सूची तय करती है, कुंजी का एक्सेस स्तर तय करता है कि काम कितना भारी हो सकता है, और जब वह व्यक्ति टीम छोड़ता है तो कुंजी भी उसके साथ समाप्त हो जाती है। कोई कृत्रिम "सर्विस खाता" नहीं है और कभी नहीं होगा — मल्टी-टेनेंट अलगाव उपयोगकर्ता से बँधा है, और बिना मालिक का ब्रिज वही होता है जो वर्षों तक चुपचाप लिखता रहता है।
1. पैनल में कुंजी जारी करें — Settings › Integration keys › New key। इसे एक नाम दें ("ERP रात का सिंक"), स्कोप और एक्सेस स्तर चुनें, और चाहें तो जीवनकाल छोटा करें। कुंजी केवल एक बार, केवल उसी स्क्रीन पर दिखाई जाती है; सर्वर इसे संग्रहीत नहीं करता। यदि यह खो जाए, तो 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 सतह पर लागू होता है, केवल कमांड कैटलॉग पर नहीं: read-only कुंजी पढ़ने वाले अनुरोध (GET/HEAD/OPTIONS) पास करती है और बाकी हर लिखने वाला अनुरोध 403 forbidden उत्तर देता है। दो जानबूझकर रखे गए अपवाद हैं और दोनों एक बारीक गेट से सुरक्षित हैं: कमांड निष्पादन एंडपॉइंट (निर्णय कमांड के अपने read_only फ़्लैग से आता है, क्योंकि न लिखने वाली कमांड भी POST से बुलाई जाती हैं) और कुंजी का स्वयं को रद्द करना (lg logout, जिसकी अनुमति read-only कुंजी पर भी है)। स्कोप, डोमेन अनुमतियाँ और एक्सेस स्तर तीन स्वतंत्र अक्ष हैं और तीनों पास होने चाहिए: read कुंजी manager स्तर पर भी नहीं लिख सकती, employee write कुंजी टीम प्रबंधित नहीं कर सकती, और loads:write डोमेन अनुमति प्रबंधन का काम नहीं खोलती। कुंजी उस सबसे कम अधिकार वाले सदस्य की ओर से जारी करें जो आपकी ज़रूरतें पूरी करता हो: भूमिका तय करती है कि आप कौन-से रिकॉर्ड देख भी सकते हैं।
read — कमांड कैटलॉग और न लिखने वाली कमांड (list, search, preview)। लिखने वाली कमांड 403 forbidden लौटाती है — पुष्टि गेट से पहले; read-only कुंजी को कभी 409 दिखता भी नहीं। रात के सिंक और रिपोर्टिंग के लिए सही विकल्प।
write — हर कमांड। जिन कमांड को पुष्टि चाहिए, वे अब भी 409 के साथ उसे माँगती हैं; confirm: true (CLI में --yes) ठीक पहले की तरह काम करता है। स्कोप कभी पुष्टि गेट को ढीला नहीं करता।
employee — हर नई कुंजी का डिफ़ॉल्ट। रोज़मर्रा का संचालन: लोड, डिमांड, बोलियाँ, ट्रिप, फ़्लीट और फ़्लीट दस्तावेज़, दस्तावेज़, संपर्क — हर वह कमांड जिसे प्रबंधन अनुमति की ज़रूरत नहीं, और साथ में फ़्लीट अनुमतियाँ। जिस कमांड को इससे अधिक चाहिए, वह error_key INSUFFICIENT_KEY_LEVEL और required_key_level: manager के साथ 422 उत्तर देती है; संबंधित REST एंडपॉइंट उसी कुंजी के साथ 403 उत्तर देता है। ERP के रात के सिंक, टेलीमैटिक्स ब्रिज या संचालन स्क्रिप्ट के लिए सही स्तर।
manager — वह सब कुछ जो कुंजी जिस व्यक्ति की ओर से काम करती है वह कर सकता है, प्रबंधन सहित: टीम सदस्य और भूमिकाएँ, कंपनी सेटिंग्स, इंटीग्रेशन कुंजियाँ, बैंक खाते और उनका सत्यापन, सहेजे गए कार्ड, कंपनी संबंध, एफ़िलिएट भुगतान। manager कुंजी कभी ऐसा अधिकार नहीं जोड़ती जो उस व्यक्ति के पास नहीं है — टीम-प्रबंधन अनुमति के बिना वह फिर भी टीम प्रबंधित नहीं कर सकती। एक्सेस स्तर लागू होने से पहले मौजूद कुंजियाँ manager कुंजियाँ हैं, इसलिए वे ठीक पहले की तरह व्यवहार करती हैं।
प्रति इंटीग्रेशन एक कुंजी — यदि CRM और ERP एक कुंजी साझा करते हैं, तो एक को काटने का मतलब दूसरे को काटना है। हर ब्रिज को उसकी अपनी कुंजी दें; सूची वैसे भी उन्हें नाम से दिखाती है।
रोटेट — एक नया टोकन जारी करता है और पुराने को तुरंत रद्द कर देता है; शेष जीवनकाल बना रहता है। लीक का संदेह होने पर और नियमित अंतराल पर इसका उपयोग करें। नए टोकन से अपडेट होने तक इंटीग्रेशन को 401 मिलता है।
रद्द करें — कुंजी स्थायी रूप से बंद हो जाती है; इसे पलटा नहीं जा सकता, ज़रूरत हो तो नई कुंजी जारी करें। यदि जिस सदस्य की ओर से कुंजी काम करती है उसे टीम से हटाया या निष्क्रिय किया जाता है, तो कुंजी अपने आप निष्क्रिय हो जाती है।
जीवनकाल और सीमा — डिफ़ॉल्ट वैधता 180 दिन है; आप इसे बनाते समय छोटा कर सकते हैं, कभी बढ़ा नहीं सकते। एक उपयोगकर्ता अधिकतम 10 सक्रिय कुंजियाँ रख सकता है। अंतिम उपयोग का समय सूची में दिखाई देता है; कभी उपयोग न हुई कुंजी यह बात स्पष्ट रूप से बताती है।
कौन प्रबंधित करता है — जारी करना, रोटेट करना, ट्रांसफ़र करना और रद्द करना टीम-प्रबंधन अनुमति वाले मैनेजरों के लिए खुला है — वही गेट जो टीम सदस्य जोड़ने या हटाने का है — और जब यह इंटीग्रेशन कुंजी से किया जाए, तो वह कुंजी manager-स्तर की होनी चाहिए। मैनेजर किसी दूसरे सदस्य की ओर से कुंजी जारी कर सकता है; ब्रिज के लिए एक समर्पित, सीमित-दायरे वाला सदस्य अनुशंसित है।
पहले दस मिनट: पैनल से आपकी पहली कॉल तक
किसी इंटीग्रेशन के सबसे महँगे मिनट पहले दस होते हैं। नीचे दिए गए चार चरण उस रास्ते को क्रम से बताते हैं; यही क्रम पैनल में एक विज़ार्ड के रूप में मौजूद है (Settings › Integration › Setup wizard), और विज़ार्ड ठीक यहाँ वर्णित एंडपॉइंट को ही बुलाता है। विज़ार्ड तक पहुँच न रखने वाला डेवलपर इस खंड को पढ़कर उसी जगह पहुँचता है।
चारों में से कोई भी चरण "मैंने भेज दिया" पर समाप्त नहीं होता। कुंजी वास्तव में काम करती है या नहीं, इसका उत्तर अनुरोध लेजर देता है; वेबहुक वास्तव में पहुँचता है या नहीं, इसका उत्तर डिलीवरी लेजर देता है। दोनों पैनल में और lg में खुले हैं। जिस सेटअप को कभी मापा नहीं जाता, वह ऐसा सेटअप है जिसके काम करने पर केवल विश्वास किया जाता है।
1. तय करें कि आप क्या करेंगे — पहले स्कोप सेट करें — कुंजी क्या देख सकती है, यह बाद में तय करने का कोई तरीका नहीं है: आप स्कोप उसे जारी करते समय चुनते हैं। दो अक्ष हैं। मोटा स्कोप (read / write) केवल इस प्रश्न का उत्तर देता है कि "क्या यह लिख सकती है"। बारीक स्कोप (डोमेन अनुमतियाँ: loads:read, invoices:write) बताता है कि यह किन डोमेन को छू सकती है, और जिस क्षण यह सेट होता है, कुंजी fail-closed हो जाती है — हर वह डोमेन जिसे आपने नहीं चुना, और हर वह एंडपॉइंट जो किसी डोमेन से नहीं जुड़ता, 403 लौटाता है। पैनल की डोमेन सूची हाथ से लिखी हुई सूची नहीं है; यह आपकी भूमिका के लाइव कमांड कैटलॉग से निकाली जाती है और दिखाती है कि हर डोमेन कितनी कमांड और REST एंडपॉइंट खोलता है। कमांड कैटलॉग, "मैं कौन हूँ" (current) और "लॉग आउट" एंडपॉइंट हमेशा स्कोप से मुक्त होते हैं: कुंजी को हमेशा स्वयं का वर्णन करने और स्वयं को बंद करने में सक्षम होना चाहिए। तीसरा अक्ष एक्सेस स्तर है: employee (डिफ़ॉल्ट) रोज़मर्रा का संचालन चलाता है, manager टीम, सेटिंग्स, कुंजियों और पैसे का काम भी करता है। जब तक ब्रिज प्रबंधन का काम नहीं करता, employee चुनें।
2. कुंजी जारी करें — टोकन एक बार दिखाया जाता है — Settings › Integration › New key। इसे एक नाम दें ("ERP रात का सिंक"), वह उपयोगकर्ता चुनें जिसकी ओर से यह चलेगी और एक्सेस स्तर चुनें, और चाहें तो जीवनकाल छोटा करें। कच्चा टोकन केवल उसी प्रतिक्रिया में लौटाया जाता है; सर्वर इसे संग्रहीत नहीं करता और पैनल में "फिर से दिखाएँ" जैसा कुछ नहीं है। यदि यह खो जाए, तो नया पाने के लिए रोटेट करें और पुराना तुरंत समाप्त हो जाता है। टोकन को कभी वर्ज़न कंट्रोल, CI लॉग या चैट विंडो में न रखें; इसे लक्ष्य सिस्टम के सीक्रेट स्टोर में रखें।
3. पहली कॉल करें — और देखें कि वह वास्तव में पहुँची — दो अनुरोध काफ़ी हैं। पहला आपकी पहचान साबित करता है (यह स्कोप से मुक्त है और हर कुंजी के साथ काम करता है): क्या स्कोप वैसा ही है जैसा आपने सोचा था, क्या स्थिति active है, क्या expires_at नज़दीक आ रहा है। दूसरा आपके चुने हुए डोमेन से असली डेटा पढ़ता है। यदि यह पास हो जाता है, तो पहचान, स्कोप, ई-मेल गेट और नेटवर्क पथ सब सही हैं। यदि नहीं, तो अनुमान न लगाएँ: कुंजी का अपना अनुरोध लेजर पंक्ति दर पंक्ति दिखाता है कि कौन-सा एंडपॉइंट किस कोड और किस स्थिर त्रुटि कुंजी (INSUFFICIENT_SCOPE, IP_NOT_ALLOWED, KEY_ACTOR_BLOCKED …) के साथ अस्वीकार हुआ। पैनल में वह लेजर "Recent requests" विंडो है; टर्मिनल में वह lg logs है। विज़ार्ड ठीक इसी लेजर पर नज़र रखता है और तब तक चरण को हरा करने से इनकार करता है जब तक वह एक वास्तविक सफल कॉल नहीं देख लेता।
4. वेबहुक सेट करें — और कुछ भी करने से पहले हस्ताक्षर का सत्यापन करें — हर मिनट पूछने की तुलना में इवेंट की प्रतीक्षा करना सस्ता है। एक https पता पंजीकृत करें, अपनी ज़रूरत के इवेंट चुनें और सब्सक्रिप्शन को अपनी कुंजी से बाँधें: यदि कुंजी रद्द होती है, तो डिलीवरी भी रुक जाती है। सीक्रेट केवल एक बार, बनाते समय, दिखाया जाता है। आपके प्राप्त करने वाले एंडपॉइंट को सबसे पहले हस्ताक्षर का सत्यापन करना चाहिए: हस्ताक्षरित स्ट्रिंग "{t}.{raw body}" है और एल्गोरिदम HMAC-SHA256 है; टाइमस्टैम्प हस्ताक्षर के भीतर है, इसलिए 300 सेकंड से पुराना कोई भी अनुरोध छोड़ दें, भले ही हस्ताक्षर वैध हो। स्थिर समय में तुलना करें और बॉडी को कभी फिर से सीरियलाइज़ न करें — जिस क्षण आप JSON को पार्स करके फिर से प्रिंट करते हैं, हस्ताक्षर मेल खाना बंद कर देता है। पैनल से, "Send test" एक असली हस्ताक्षरित ping भेजता है और आप डिलीवरी को प्रयास दर प्रयास देख सकते हैं।
सैंडबॉक्स: प्रोडक्शन को छुए बिना लिखने का अभ्यास करें
प्रीफ़्लाइट (dry_run) बताता है कि कोई कमांड क्या करेगी; लेकिन आइडेम्पोटेंसी वास्तव में replay करती है या नहीं, वेबहुक वास्तव में डिलीवर होता है या नहीं, त्रुटि शाखाएँ कैसी दिखती हैं और क्रेडिट कहाँ से आता है — यह केवल एक वास्तविक लेखन में ही देखा जा सकता है। सैंडबॉक्स इसी के लिए है: एक अलग टेनेंट जो आपकी कंपनी का प्रतिबिंब है — वही कोड, वही कमांड कैटलॉग — और कभी आपके लाइव लेजर को नहीं छूता।
सैंडबॉक्स कोई अनुरोध फ़्लैग नहीं, बल्कि एक टेनेंट है। आपकी कंपनी के लिए खोली गई एक अलग Logistivo कंपनी: उसका अपना उपयोगकर्ता, अपना पैकेज, अपना क्रेडिट लेजर, अपने वेबहुक सब्सक्रिप्शन। वातावरण कुंजी की कंपनी से निकाला जाता है और कॉल करने वाला उसे नहीं भेज सकता, इसलिए यदि आप गलत प्रोफ़ाइल भी चुन लें, तो अनुरोध सर्वर की ओर 403 ENVIRONMENT_MISMATCH के साथ रुक जाता है। "मुझे लगा मैं सैंडबॉक्स में लिख रहा था और प्रोडक्शन में लिख दिया" — यह संरचनात्मक रूप से असंभव है।
सतह एक जैसी है — मापी हुई: सैंडबॉक्स कुंजी जो कैटलॉग पाती है, वह वही है जो आपकी लाइव कुंजी पाती है (शिपर कुंजी पर, दोनों ओर 646 कमांड)। जो ब्रिज सैंडबॉक्स में काम करता है, वह प्रोडक्शन में काम करता है; आपको कुछ भी दो बार नहीं सीखना पड़ता।
सैंडबॉक्स खाली नहीं खुलता: इसमें जनरेट किया गया (कॉपी नहीं किया गया) प्रारंभिक डेटा होता है — संपर्क, दोनों दिशाओं के लोड, और डिमांड। नाम खुले तौर पर काल्पनिक हैं और ई-मेल पते @sandbox.invalid डोमेन में हैं; किसी भी वास्तविक टेनेंट की पंक्ति कभी पढ़ी, क्लोन या टेम्पलेट के रूप में उपयोग नहीं की जाती।
जानबूझकर कोई रीसेट बटन नहीं है, और कोई भी रिकॉर्ड, फ़ाइल या दस्तावेज़ कभी हटाया नहीं जाता। यदि आप नई शुरुआत चाहते हैं, तो नवीनीकरण एक नया जनरेशन खोलता है और पुराना सेवानिवृत्त होकर बना रहता है। कुछ सौ जमा हुई अभ्यास पंक्तियों की लागत, गलत टेनेंट से जुड़ी किसी हटाने वाली प्रक्रिया की तुलना में कुछ भी नहीं है।
1. सैंडबॉक्स खोलें — प्रति कंपनी एक सैंडबॉक्स। एंडपॉइंट को टीम-प्रबंधन अनुमति (team.manage) चाहिए, इसलिए यह काम आपकी कंपनी का कोई एडमिनिस्ट्रेटर करता है। यदि यह पहले से मौजूद है, तो वही एंडपॉइंट GET पर उसकी स्थिति बताता है: कंपनी id, शेष क्रेडिट, सक्रिय कुंजियों की संख्या, सब्सक्रिप्शन, जनरेशन इतिहास और सीमाएँ।
2. सैंडबॉक्स कुंजी जारी करें और उसे दूसरी प्रोफ़ाइल के रूप में रखें — कुंजी सैंडबॉक्स के अपने ब्रिज उपयोगकर्ता की ओर से जारी होती है और environment: sandbox मुहर के साथ लौटती है; कच्चा टोकन केवल उसी एक प्रतिक्रिया में दिखाई देता है। lg की ओर अपनी लाइव कुंजी को न बदलें — दोनों को अलग-अलग प्रोफ़ाइल के रूप में रखें; --sandbox और --live एक बार चलाने के लिए चुनने वाले विकल्प हैं।
3. वास्तव में लिखें — यहाँ कोई --dry-run नहीं; लिखना ही पूरा उद्देश्य है। वही आइडेम्पोटेंसी कुंजी दो बार भेजें और देखें कि दूसरी प्रतिक्रिया status: replayed के रूप में लौटती है — सैंडबॉक्स में यही मापा गया परिणाम है। किसी गेट वाली कमांड को जानबूझकर बिना पुष्टि के बुलाएँ और 409 बॉडी पढ़ें; अपने स्कोप से बाहर की कोई कमांड आज़माएँ और अस्वीकृति पढ़ें। इनमें से कुछ भी आपके लाइव लेजर में कोई निशान नहीं छोड़ता: उसी रन के दौरान आपका लाइव शेष अपरिवर्तित रहता है।
4. लाइव जाने से पहले चेकलिस्ट पढ़ें — go-live एंडपॉइंट उस आधार पर उत्तर देता है जो आपने सैंडबॉक्स में वास्तव में किया: क्या आपने लिखा, क्या आपने त्रुटि शाखाएँ देखीं, क्या कोई वेबहुक डिलीवर हुआ, क्या आपने रिसीवर को अभ्यास वाले पते से हटाया, क्या आपने कुंजी पर समाप्ति तिथि लगाई। हर आइटम pass / todo / unknown के रूप में लौटता है। उसी प्रतिक्रिया में आपके द्वारा वास्तव में बुलाई गई कमांड से निकाला गया एक स्कोप प्रस्ताव भी होता है — इसका उपयोग अपनी लाइव कुंजी को ज़रूरत से ज़्यादा चौड़ा रखे बिना जारी करने के लिए करें।
क्रेडिट और इनवॉइसिंग — सैंडबॉक्स का अपना क्रेडिट लेजर है और आपका लाइव शेष नहीं बदलता। यह एक संरचना है, कोई जाँच नहीं: क्रेडिट प्रति कंपनी गिना जाता है और सैंडबॉक्स एक अलग कंपनी है। यह मुफ़्त स्तर पर खुलता है, इसकी कोई भुगतान विधि नहीं होती और यह मासिक वसूली विंडो के बाहर रहता है — यह किसी भी रास्ते से किसी इनवॉइस तक नहीं पहुँच सकता।
मार्केटप्लेस — सैंडबॉक्स में खोली गई डिमांड वास्तविक कैरियरों की स्क्रीन पर नहीं दिखती और उनके ई-मेल या पुश इनबॉक्स तक नहीं पहुँचती; और आप भी वास्तविक डिमांड नहीं देखते। यह विभाजन दोनों ओर समान है और दो अलग-अलग क्वेरी में लागू होता है: कोई डिमांड किसे दिखाई देती है और किसे भेजी जाती है — ये अलग-अलग प्रश्न हैं।
वेबहुक — सब्सक्रिप्शन भी वातावरण की मुहर रखते हैं। सैंडबॉक्स इवेंट कभी लाइव सब्सक्रिप्शन पर डिलीवर नहीं होता और लाइव इवेंट कभी सैंडबॉक्स सब्सक्रिप्शन तक नहीं पहुँचता; जिस सब्सक्रिप्शन की मुहर बदल गई हो, उसके लिए कोई डिलीवरी खोली ही नहीं जाती। क्योंकि सब्सक्रिप्शन की सीमा प्रति कंपनी है, आपके अभ्यास वाले सब्सक्रिप्शन आपके लाइव कोटे में से नहीं खाते।
प्रारंभिक (सीड) डेटा — सैंडबॉक्स के भीतर के नमूना रिकॉर्ड जनरेट किए गए हैं, वास्तविक टेनेंट से कभी कॉपी नहीं किए गए। सीडिंग आइडेम्पोटेंट है: दूसरी कॉल आपके अपने रिकॉर्ड के ऊपर दूसरी सीड नहीं बिछाती।
वही कैटलॉग — सैंडबॉक्स में भी आपकी भूमिका वही है, और कमांड सूची एक जैसी है — मापी हुई, दोनों ओर 646 कमांड। सैंडबॉक्स कोई काट-छाँट किया हुआ डेमो नहीं है; यह आपकी कंपनी का जुड़वाँ है।
आज की सीमा: सैंडबॉक्स कुंजी से वेबहुक सब्सक्रिप्शन प्रबंधित नहीं किए जा सकते — सब्सक्रिप्शन एंडपॉइंट को टीम-प्रबंधन अनुमति (team.manage) चाहिए, और सैंडबॉक्स के ब्रिज उपयोगकर्ता के पास कोई टीम भूमिका नहीं है, इसलिए `lg --sandbox webhooks …` आज 403 उत्तर देता है। पूरी कमांड सतह काम करती है — प्रतिबंध केवल सब्सक्रिप्शन लेजर पर है। यदि आप सैंडबॉक्स में वेबहुक का अभ्यास करना चाहते हैं, तो सपोर्ट से संपर्क करें; यह मापा गया है और एक खुली कमी के रूप में दर्ज है।
GET /api/common/integration-sandbox — स्थिति: क्या यह मौजूद है, कौन-सी कंपनी, शेष क्रेडिट, सक्रिय कुंजियों और सब्सक्रिप्शन की संख्या, जनरेशन इतिहास, सीमाएँ, और एक ट्रिगर गाइड जो दिखाती है कि कौन-सी कमांड कौन-सा इवेंट उठाती है।
POST /api/common/integration-sandbox — सैंडबॉक्स खोलता है (प्रति कंपनी एक, आइडेम्पोटेंट)। team.manage अनुमति आवश्यक है।
POST /api/common/integration-sandbox/keys — 201 + कुंजी और कच्चा टोकन (केवल यहीं, केवल एक बार)। environment: sandbox मुहर कंपनी से निकाली जाती है; कॉल करने वाला उसे नहीं भेज सकता।
GET /api/common/integration-sandbox/go-live — go-live चेकलिस्ट और एक स्कोप प्रस्ताव — सैंडबॉक्स में आपके वास्तविक ट्रैफ़िक से गणना किया हुआ।
POST /api/common/integration-sandbox/renew — एक नया सैंडबॉक्स जनरेशन खोलता है और पिछले को सेवानिवृत्त कर देता है।
कमांड मॉडल
व्याकरण एक ही है और उसमें कोई अपवाद नहीं है। किसी कमांड को कैसे बुलाना है, यह जानने के लिए आपको केवल वही चाहिए जो कैटलॉग उसके बारे में कहता है।
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 — क्रिया (verb) — आप उस इकाई के साथ क्या करते हैं; यह एक बंद शब्दावली से ली जाती है जो केवल सोच-समझकर लिए गए निर्णय से बढ़ती है: सरल क्रियाएँ (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 — सूची कमांड पर पंक्तियों की संख्या। अधिकतम सीमा हर कमांड के पैरामीटर विवरण में बताई गई है — सामान्य list कॉल पर आमतौर पर 20 और sync मोड में (cursor या updated_since के साथ) 100 तक।
--json — कच्चा (raw) JSON आउटपुट।
--json — कच्चा JSON प्रिंट करता है। स्क्रिप्ट के लिए यही एकमात्र सही रूप है: डिफ़ॉल्ट संरेखित तालिका इंसानों के लिए है, अपने कॉलम डेटा से चुनती है और बिना सूचना के अपना लेआउट बदल सकती है। कभी भी ऐसी स्क्रिप्ट न लिखें जो तालिका वाले आउटपुट को पार्स करे।
--yes, -y — पुष्टि गेट पार करता है (HTTP पर confirm: true)। इसका उपयोग केवल उसी स्क्रिप्ट में करें जो जानती हो कि वह क्या करने जा रही है; अपरिवर्तनीय कमांड पर यह फ़्लैग "इसे पलटा नहीं जा सकता" का संक्षिप्त रूप है।
--idempotency-key= — लिखने वाली कमांड को दोबारा प्रयास करना सुरक्षित बनाता है। उसी कुंजी के साथ दूसरी कॉल कमांड को फिर से नहीं चलाती; वह पहला परिणाम लौटाती है। यदि आप पुनः प्रयास का लूप बनाते हैं, तो कुंजी खुद (स्वयं) जनरेट करें और हर प्रयास पर वही कुंजी भेजें।
--dry-run — कमांड के बजाय एक प्रीफ़्लाइट चलाता है: वैलिडेशन, गेट और क्रेडिट गणना चलती हैं, कुछ भी लिखा नहीं जाता (प्रीफ़्लाइट खंड देखें)। हर कमांड पर और lg batch पर मान्य।
--refresh — कैटलॉग को ज़बरदस्ती रीफ़्रेश करता है। lg कैटलॉग को एक घंटे के लिए कैश करता है; यदि आपको पता है कि सर्वर पर अभी-अभी कोई कमांड जोड़ी गई है, तो प्रतीक्षा करने के बजाय इसका उपयोग करें।
--help, -h — कमांड का कैटलॉग विवरण, हर पैरामीटर, उसका प्रकार, उसके enum मान और यह कि वह अनिवार्य है या नहीं — सब प्रिंट करता है। क्लाइंट के भीतर कोई सहायता फ़ाइल नहीं है।
--profile=, --sandbox, --live — यह एक कॉल किस प्रोफ़ाइल के रूप में चलानी है। --sandbox और --live उस प्रोफ़ाइल को चुनते हैं जिसमें सैंडबॉक्स या लाइव कुंजी है; वातावरण सर्वर पर कुंजी से निकाला जाता है, इसलिए बेमेल होने पर कमांड गलत जगह लिखने के बजाय 403 ENVIRONMENT_MISMATCH के साथ रुक जाती है।
--base-url, --timeout, --verbose, --no-color, --version — क्रमशः: एक कमांड को किसी दूसरे सर्वर की ओर निर्देशित करना, सेकंड में टाइमआउट, अनुरोध/प्रतिक्रिया का विवरण, ANSI रंग बंद करना, और क्लाइंट का संस्करण।
वास्तविक उदाहरण
नीचे दी गई हर कमांड आज कैटलॉग में मौजूद है; यहाँ कोई भी नाम या पैरामीटर गढ़ा हुआ नहीं है। आउटपुट संक्षिप्त किए गए हैं। आउटपुट `data.result` स्तर दिखाते हैं; HTTP पर यही ऑब्जेक्ट `{success, data:{…}}` लिफ़ाफ़े (envelope) के भीतर आता है (HTTP कमांड API देखें)।
इस समय सड़क पर चल रहे लोड — 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
देश का id निकालें — lg countries search --query=Germany --json
निकाले गए id से फ़िल्टर करें — 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
क्लाइंट के बिना: HTTP कमांड API
lg एक सुविधा है, एकमात्र दरवाज़ा नहीं। कैटलॉग और निष्पादन दोनों तीन HTTP एंडपॉइंट से होकर जाते हैं (फ़ाइलों के लिए एक चौथा, अपलोड एंडपॉइंट है — "फ़ाइलें लेने वाली कमांड" देखें); ERP या CRM इंटीग्रेशन सीधे यहीं जुड़ता है। पहचान एक व्यक्तिगत एक्सेस टोकन है जो Authorization: Bearer में भेजा जाता है। हर एक प्रतिक्रिया एक ही लिफ़ाफ़े (envelope) में आती है: `{ "success": bool, "data": { … }, "code": "…", "message": { … } }`। पूरा कॉन्ट्रैक्ट `data` के भीतर रहता है — `contract_version`, `command`, `status` और, कमांड के आउटपुट के रूप में, `result`; विफलता पर `error_code`, `error_key` और `error`। जगह बचाने के लिए इस पृष्ठ के प्रतिक्रिया उदाहरण लिफ़ाफ़े के बजाय `data` ऑब्जेक्ट दिखाते हैं; अपने कोड में `data` को खोलना (unwrap करना) न भूलें। `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 कोड पढ़ना, वाहन के पंजीकरण दस्तावेज़ से वाहन बनाना, फ़ोटो से पैलेट का अनुमान लगाना, कंपनी का कोई दस्तावेज़ अपलोड करना, इनवॉइस का पैकिंग लिस्ट से मिलान करना। ब्राउज़र में आप फ़ाइल को किसी फ़ॉर्म में डाल देते हैं; बाकी हर जगह इसमें दो चरण लगते हैं — फ़ाइल अपलोड करें, फिर उसकी id कमांड को दें।
कोई पैरामीटर तब फ़ाइल लेता है जब उसका नाम attachment_uuid या attachment_uuids पर समाप्त होता है — सूची के भीतर photos[].attachment_uuid, चेक पर front_attachment_uuid। आपको यह याद रखने की ज़रूरत नहीं है: हर कैटलॉग पंक्ति सटीक पथों के साथ file_params रखती है, स्कीमा उन फ़ील्ड को चिह्नित करता है (format: uuid, x-logistivo-file: true), और कैटलॉग प्रतिक्रिया एक attachments ब्लॉक रखती है जिसमें अपलोड पता, स्वीकृत प्रकार, आकार सीमाएँ और जीवनकाल (time to live) होता है। lg help भी इन्हें दिखाता है।
अपलोड करना एक लेखन है, इसलिए read स्कोप वाली कुंजी अपलोड नहीं कर सकती; write स्कोप वाली कोई भी कुंजी, किसी भी एक्सेस स्तर पर, कर सकती है। अपलोड उपयोगकर्ता के होते हैं, कुंजी के नहीं: एक ही उपयोगकर्ता की दो कुंजियाँ वही अपलोड देखती हैं, और कोई भी किसी दूसरे के अपलोड का उपयोग नहीं कर सकता। जो id अज्ञात, समाप्त या आपकी नहीं है, वह बस नहीं मिलती, और कारण नहीं बताया जाता।
डैशबोर्ड चैट के अटैचमेंट और कमांड अपलोड अलग-अलग स्थान हैं: सहायक चैट में जोड़ी गई फ़ाइल को id से किसी कमांड को नहीं दिया जा सकता, और कमांड अपलोड कभी किसी चैट थ्रेड में दिखाई नहीं देता।
अपलोड कोई कमांड नहीं है और अपने आप में उसका कोई व्यावसायिक प्रभाव नहीं होता: जब तक कोई कमांड उस id का उपयोग नहीं करती, आपके डेटा के साथ कुछ नहीं होता। इसीलिए अपलोड करना कभी पुष्टि नहीं माँगता — फ़ाइल का उपभोग करने वाली कमांड ही गेट रखती है।
1. lg: स्थानीय पथ के आगे @ लगाएँ — lg पहले फ़ाइल अपलोड करता है, फिर लौटाई गई id के साथ कमांड चलाता है; @ के बिना दिया गया मान आपके द्वारा पहले अपलोड की गई फ़ाइल की id है। सूचियाँ अल्पविराम से अलग किए गए पथ या दोहराया गया फ़्लैग लेती हैं, नेस्टेड फ़ील्ड JSON लेते हैं, और जब कमांड में ठीक एक शीर्ष-स्तरीय फ़ाइल फ़ील्ड हो, तो --file एक शॉर्टकट है। कुछ भी भेजे जाने से पहले lg हर फ़ाइल को स्थानीय रूप से सत्यापित करता है (मौजूद है या नहीं, आकार, प्रकार), और lg batch बैच चलने से पहले हर अलग फ़ाइल को एक बार अपलोड करता है।
2. HTTP: अपलोड करें, फिर attachment_uuid पास करें — फ़ाइल को file नाम के फ़ील्ड में multipart/form-data के रूप में भेजें। नया अपलोड 201 उत्तर देता है; उसी उपयोगकर्ता द्वारा वही फ़ाइल दोबारा अपलोड करने पर replayed स्थिति और उसी id के साथ 200 उत्तर मिलता है, और कुछ भी लिखा नहीं जाता। इस पृष्ठ पर हर जगह की तरह, उदाहरण लिफ़ाफ़े के भीतर का 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) — उसे हटाया नहीं जाता। यदि कोई कमांड इस कारण से विफल हो, तो फिर से अपलोड करें।
वही फ़ाइल, वही id — वही फ़ाइल दोबारा अपलोड करने पर (वही नाम, आकार और सामग्री) नई फ़ाइल लिखने के बजाय मौजूदा id लौटती है, बशर्ते उसमें कम से कम एक घंटा बचा हो, और यह आपकी दैनिक सीमा में नहीं गिना जाता।
दैनिक सीमाएँ — प्रति उपयोगकर्ता प्रतिदिन 300 अपलोड (TOO_MANY_FILES) और प्रति कंपनी प्रतिदिन 2 GB (DAILY_LIMIT_REACHED); दोनों retry_after के साथ 429 उत्तर देते हैं।
POST /api/common/commands:upload — file फ़ील्ड में multipart अपलोड। नए अपलोड पर 201, उसी फ़ाइल पर replayed स्थिति के साथ 200। data.attachment लौटाता है: attachment_uuid, filename, mime_type, size_bytes, sha256, extraction_status, expires_at और reused।
पुष्टि गेट और अपरिवर्तनीय कमांड
कैटलॉग की हर कमांड दो फ़्लैग रखती है: confirmation_needed (क्या चलने से पहले उसे स्पष्ट स्वीकृति चाहिए) और irreversible (क्या उसका प्रभाव पलटा जा सकता है)। ये अलग-अलग प्रश्न हैं, और दोनों सर्वर पर लागू किए जाते हैं, क्लाइंट की भलमनसाहत पर नहीं छोड़े जाते।
गेट ज़िम्मेदारी के बारे में है, व्यावसायिक नियमों के बारे में नहीं। बोली लगाना माल ढुलाई अनुबंध की ओर पहला कदम है; इनवॉइस जारी करने से एक लेखांकन प्रविष्टि बनती है; स्टॉक की आवाजाही एक लेजर को बदलती है। इनमें से कोई भी ऐसा काम कभी नहीं होना चाहिए जिसे आप गलती से दो बार चला सकें।
गेट प्रभावी (EFFECTIVE) कमांड से पढ़ा जाता है। जब एक कमांड दूसरी को लपेटती है — जैसा चैट का सामान्य एक्ज़ीक्यूटर करता है — तो गेट उस कमांड के फ़्लैग से आता है जो वास्तव में चलेगी, रैपर से नहीं। किसी निश्चित फ़्लैग के साथ दो में से एक विफलता अनिवार्य होती: या तो इनवॉइस कमांड बिना पुष्टि के चल जाती, या हर देश-खोज एक पुष्टि कार्ड खड़ा कर देती।
read_only और बिना गेट (ungated) एक ही चीज़ नहीं हैं। तीन अलग-अलग अवस्थाएँ हैं: 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 के साथ दोहराएँ (CLI में --yes)। अपरिवर्तनीय कमांड इस तरह चिह्नित होती हैं कि वे अधिकतम एक बार चलें।
प्रीफ़्लाइट: देखें कि कोई लिखने वाली कमांड क्या करेगी, उसे चलाए बिना
ERP ब्रिज जोड़ने का सबसे महँगा चरण यह पता लगाना है कि आपकी बॉडी सही है या नहीं, और वह भी कमांड को वास्तव में चलाकर: लाइव लेजर में एक ड्राफ़्ट इनवॉइस, जला हुआ क्रेडिट, हाथ से सफ़ाई। dry_run इसे खत्म करता है — आप अनुरोध में एक फ़ील्ड जोड़ते हैं, कमांड नहीं चलती, और आप पढ़ लेते हैं कि क्या होता।
रजिस्ट्री में आज 721 कमांड हैं; उनमें से 327 केवल पढ़ती हैं और कुछ नहीं लिखतीं। शेष 394 लिखने वाली कमांड में से 346 गेट वाली हैं: confirm के बिना बुलाए जाने पर वे पहले से ही 409 लौटाती हैं और बताती हैं कि वे क्या करेंगी। कमी बाकी 48 में थी — इनवॉइस ड्राफ़्ट, निर्यात-दस्तावेज़ ड्राफ़्ट, लाइन आइटम: ठीक वही शृंखला जिसे कोई ब्रिज सबसे पहले जोड़ता है। उनके लिए बुलाने का मतलब था कर देना।
गेट वाली कमांड पर भी एक दूसरी कमी थी: स्कीमा वैलिडेशन गेट के बाद चलता है। इसलिए किसी गायब आर्गुमेंट वाली कॉल को पहले पुष्टि कार्ड मिलता, उसकी पुष्टि होती, और तभी जाकर सुनाई देता कि "यह फ़ील्ड गायब है"। प्रीफ़्लाइट दोनों प्रश्नों का उत्तर एक ही राउंड ट्रिप में देता है।
और ब्रिज का सबसे आम — और सबसे देर से पकड़ा जाने वाला — बग यह है: आप ऐसा फ़ील्ड भेजते हैं जो स्कीमा में नहीं है (जहाँ recipient_contact_id अपेक्षित है वहाँ customer_id), सर्वर उसे चुपचाप छोड़ देता है, कमांड 200 लौटाती है और रिकॉर्ड गलत जगह पहुँच जाता है। प्रीफ़्लाइट प्रतिक्रिया ऐसे फ़ील्ड को arguments.ignored के अंतर्गत नाम से सूचीबद्ध करती है; कोई त्रुटि संदेश कभी ऐसा नहीं करेगा।
प्रीफ़्लाइट कुछ नहीं लिखता, और यह मापन से पहले संरचना की बात है: प्रीफ़्लाइट का रास्ता कभी कमांड के हैंडलर में प्रवेश नहीं करता, इसलिए यह हर कमांड पर लागू होता है, बाद में जोड़ी गई कमांड पर भी। जारी होते समय इसे मापा भी गया था: उस समय कैटलॉग की हर लिखने वाली कमांड का प्रीफ़्लाइट करते हुए (दो आर्गुमेंट सेट, दो भूमिकाएँ, 178 प्रीफ़्लाइट) जारी हुआ हर SQL स्टेटमेंट रिकॉर्ड किया गया। एक भी INSERT/UPDATE/DELETE नहीं, एक भी कतारबद्ध जॉब नहीं, एक भी ईमेल नहीं; 31 तालिकाओं में पंक्तियों की संख्या और क्रेडिट शेष अपरिवर्तित रहे।
एग्ज़िट कोड वही होता है जो असली कॉल देती — चल जाती तो 0, पुष्टि गेट 4, आइडेम्पोटेंसी टकराव 2, बाकी सब 1 — इसलिए "lg … --dry-run || exit" किसी CI चरण में एक सार्थक गेट है।
1. इसे dry_run के साथ बुलाएँ — अनुरोध बॉडी में "dry_run": true जोड़ें। वैलिडेशन, भूमिका और स्कोप गेट, लक्ष्य का निर्धारण और क्रेडिट गणना — सब चलते हैं; कमांड नहीं चलती।
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 रेट लिमिट।
read स्कोप वाली कुंजी किसी लिखने वाली कमांड का dry-run नहीं कर सकती — उसे 403 मिलता है। प्रीफ़्लाइट इस प्रश्न का उत्तर देता है कि "अगर मैं इसे अभी, इसी कुंजी से बुलाऊँ तो क्या होगा"; read कुंजी को हरी झंडी देना और फिर असली कॉल पर 403 देना ठीक वही आश्चर्य होता जिसे रोकने के लिए प्रीफ़्लाइट मौजूद है।
आइडेम्पोटेंसी कुंजी उपयोग में नहीं आती — प्रीफ़्लाइट के दौरान भेजी गई कुंजी कोई लेजर पंक्ति नहीं खोलती, और समाप्त हो चुका लॉक मुक्त नहीं किया जाता। इसलिए वही कुंजी भेजें जिसे आप असली कॉल में उपयोग करना चाहते हैं: प्रीफ़्लाइट बताता है कि वह अभी भी खाली है, किसी पिछले रन को दोहराएगी (replay), या किसी दूसरी कमांड से टकराती है।
यह confirm के साथ जुड़ता है — dry_run और confirm एक साथ भेजें, तो प्रश्न बन जाता है "अगर मैं पुष्टि करूँ तो क्या होगा?"। फिर भी कुछ नहीं चलता।
बैच प्रीफ़्लाइट प्रति बैच होता है — commands:batch भी dry_run लेता है, लेकिन यह फ़्लैग बैच का है, किसी आइटम का नहीं (इसे किसी आइटम पर भेजना 422 है)। आपको प्रति-आइटम रिपोर्ट और बैच की कुल क्रेडिट लागत मिलती है; अपर्याप्त शेष राशि की सूचना दी जाती है, कॉल अस्वीकार नहीं की जाती।
यह मुफ़्त नहीं है — हर प्रीफ़्लाइट असली क्वेरी (पूर्वावलोकन, शेष राशि) चलाता है और रेट लिमिट में गिना जाता है। हर डिप्लॉय पर पूरे कैटलॉग का प्रीफ़्लाइट न करें; केवल उन कमांड का प्रीफ़्लाइट करें जिन्हें आपने बदला है।
आइडेम्पोटेंसी: दोबारा प्रयास करने से डुप्लिकेट क्यों नहीं बनते
ERP आपका त्रुटि संदेश नहीं पढ़ता, आपकी स्क्रीन नहीं देखता, और टाइमआउट के बाद वही अनुरोध फिर से भेज देगा। यह खंड ठीक इसी व्यवहार के लिए है।
idempotency_key वाली कॉल अधिकतम एक बार चलती है। दूसरी कॉल कमांड को फिर से निष्पादित नहीं करती; वह दर्ज परिणाम को replayed स्थिति के साथ लौटाती है। जब नेटवर्क टूटता है, जब कोई अनुरोध टाइमआउट होता है, या जब कोई कतार एक ही जॉब को दो बार उठा लेती है, तो आपको डुप्लिकेट इनवॉइस के बजाय पहला परिणाम मिलता है।
हर लिखने वाली कमांड पर कुंजी का उपयोग करें। कैटलॉग का read_only फ़ील्ड यह अंतर आपको मुफ़्त में देता है: read_only: false वाली हर कमांड को आइडेम्पोटेंसी कुंजी मिलनी चाहिए।
आपकी पुनः प्रयास रणनीति में एक्सपोनेंशियल बैकऑफ़ होना चाहिए और हर प्रयास पर वही कुंजी भेजी जानी चाहिए। हर प्रयास के लिए नई कुंजी जनरेट करना बिल्कुल वैसा ही है जैसे आइडेम्पोटेंसी का उपयोग ही न करना। एक ही कुंजी समानांतर में न भेजें: अधिकतम-एक-बार (at-most-once) की गारंटी क्रमिक पुनः प्रयासों के लिए है, एक-दूसरे से होड़ करते दो अनुरोधों के लिए नहीं।
जाल 1 — विफलता भी लॉक हो जाती है — यदि पहले निष्पादन को किसी व्यावसायिक नियम ने अस्वीकार कर दिया था (failed), तो उसी कुंजी के साथ दूसरी कॉल वही त्रुटि और वही error_key लौटाती है, और दोबारा प्रयास नहीं करती। आर्गुमेंट ठीक करके फिर से प्रयास करने के लिए एक नई कुंजी चाहिए। कुंजी एक प्रयास का प्रतिनिधित्व करती है, किसी इरादे का नहीं।
जाल 2 — बड़ा परिणाम बिना बॉडी के दोहराया जाता है — लेजर कोई परिणाम तभी संग्रहीत करता है जब वह 64 KB से छोटा हो। बड़ा परिणाम replayed स्थिति के साथ, लेकिन खाली बॉडी के साथ दोहराया जाता है। आपके इंटीग्रेशन को बॉडी के बजाय "replayed" संकेत पर भरोसा करना चाहिए, और डेटा को संबंधित get कमांड से प्राप्त करना चाहिए।
जाल 3 — एक कुंजी एक ही कमांड की होती है — उसी कुंजी को किसी दूसरी कमांड के साथ भेजने पर conflicting_command के साथ 409 idempotency_conflict मिलता है; कुछ नहीं चलता और कुछ भी दोहराया नहीं जाता। जो क्लाइंट एक कुंजी को दो क्रियाओं में साझा करता है, वह टूटा हुआ है, और उसे यह किसी चुपचाप हुए replay से नहीं, बल्कि एक त्रुटि से पता चलता है।
जाल 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 खिसकता रहता है। दो पेजों के बीच डाली गई एक पंक्ति आपसे कोई रिकॉर्ड छुड़वा देती है या उसे दो बार गिनवा देती है, और वह भी चुपचाप। कर्सर केवल आगे की ओर चलता है, इसलिए बीच में डाला या अपडेट किया गया रिकॉर्ड सूची के अंत में पहुँचता है: कुछ भी खोता नहीं, कुछ भी डुप्लिकेट नहीं होता।
पूरा प्रारंभिक लोड भी यही तंत्र है: updated_since=1970-01-01T00:00:00Z से शुरू करें और next_cursor का पालन तब तक करें जब तक वह null न हो जाए। कोई अलग “export” एंडपॉइंट नहीं है क्योंकि उसकी कोई ज़रूरत नहीं है।
lg के साथ भी यही: lg loads list --updated_since=2026-09-01T00:00:00Z --limit=100 --json, फिर lg loads list --cursor= --json।
अगले सिंक के लिए updated_since को आपके द्वारा देखे गए सबसे बड़े updated_at पर सेट करें। टाइमस्टैम्प की सटीकता एक सेकंड की है, इसलिए सीमा पर पड़ने वाला रिकॉर्ड दो बार आ सकता है — यह तब तक हानिरहित है जब तक आप अपनी ओर external_ref या code के आधार पर upsert करते हैं। updated_since या cursor के बिना कमांड चैट मोड में चलती है: इंसानों के लिए क्रम, अधिकतम 20 पंक्तियाँ, next_cursor null और truncated यह बताते हुए कि “और भी है”। सिंक के लिए उस मोड का उपयोग न करें।
इस खंड की मशीन-पठनीय त्रुटि कुंजियाँ: INVALID_CURSOR, INVALID_UPDATED_SINCE, DUPLICATE_EXTERNAL_REF, EXTERNAL_REF_TOO_LONG, EXTERNAL_REF_INVALID। ये सभी बॉडी में error_code: "failed" और result.error_key के साथ HTTP 422 उत्तर देती हैं। शाखा कुंजी के आधार पर बनाएँ, पाठ के आधार पर कभी नहीं।
updated_since — ISO-8601 टाइमस्टैम्प (UTC अनुशंसित, उदाहरण: 2026-09-01T00:00:00Z)। इस क्षण पर या उसके बाद अपडेट हुई पंक्तियाँ। यह कमांड को sync मोड में डाल देता है: निश्चित क्रम (updated_at, id) आरोही, limit की अधिकतम सीमा 100।
cursor — पिछली प्रतिक्रिया का next_cursor, ज्यों का त्यों। यह अपारदर्शी और हस्ताक्षरित है: इसे कभी स्वयं न बनाएँ या संपादित न करें, किसी दूसरी कंपनी या दूसरी कमांड का कर्सर कभी दोबारा उपयोग न करें; ये सभी INVALID_CURSOR के साथ अस्वीकार कर दिए जाते हैं।
limit — पेज का आकार। sync मोड में 1-100 (डिफ़ॉल्ट 10)।
next_cursor (प्रतिक्रिया) — अगले पेज के लिए कर्सर। null का अर्थ है कि सूची पूरी हो गई; “क्या और है” का यही एकमात्र सही उत्तर है।
total (प्रतिक्रिया) — फ़िल्टर से मेल खाने वाली पंक्तियाँ, पेज से स्वतंत्र — प्रगति रिपोर्टिंग के लिए।
आपकी अपनी कुंजी: external_ref
हमारी ऑटो-इंक्रीमेंट id (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=... — ये सभी काम करती हैं; list और search कमांड पर --external_ref= एक सटीक-मिलान फ़िल्टर है।
प्रति कंपनी अद्वितीय — उसी कुंजी वाला दूसरा रिकॉर्ड 422 और result.error_key = DUPLICATE_EXTERNAL_REF के साथ अस्वीकार कर दिया जाता है; किसी दूसरी कंपनी की कुंजी आपको “नहीं मिला” उत्तर देती है। मिलान केस-असंवेदनशील है (ord-1 = ORD-1)। संग्रहीत (archived) रिकॉर्ड अपनी कुंजी रखता है; कुंजी दोबारा उपयोग करने से पहले उसे पुनर्स्थापित करें।
साथ में idempotency_key भी भेजें — नेटवर्क टाइमआउट के बाद पुनः प्रयास डुप्लिकेट बनाने के बजाय पहला परिणाम लौटाता है। दोनों एक-दूसरे की जगह नहीं ले सकते: external_ref आपकी व्यावसायिक कुंजी है, idempotency_key एक प्रयास की पहचान करती है।
आउटगोइंग वेबहुक: कुछ होने पर हम आपको POST करते हैं
यहाँ तक सब कुछ पुल (pull) था: आप पूछते हैं, हम उत्तर देते हैं। किसी ERP ब्रिज को यह जानने के लिए हर मिनट पूछना पड़ता था कि किसी लोड की स्थिति बदली, कोई इनवॉइस जारी हुआ या कोई बोली आई। अब और नहीं: एक https पता पंजीकृत करें, उन इवेंट को चुनें जिनकी आपको परवाह है, और उनके होते ही एक हस्ताक्षरित POST पहुँचता है।
पुश को पुल के साथ-साथ जोड़ा गया, उसकी जगह नहीं। इंक्रीमेंटल सिंक (updated_since + cursor) अछूता है और अब भी सही उपकरण है: पहला पूरा लोड, इतिहास का बैकफ़िल और "क्या मुझसे कुछ छूट गया" का उत्तर — सब वहीं रहते हैं। वेबहुक विलंब को मिनटों से घटाकर सेकंड कर देते हैं। एक स्वस्थ ब्रिज दोनों का उपयोग करता है — वेबहुक ट्रिगर के रूप में, सिंक सुरक्षा जाल के रूप में।
पेलोड एक संकेत (signal) है, रिकॉर्ड की प्रति नहीं। इसमें पहचानकर्ता होते हैं (id, आपका अपना external_ref, status, समय); विवरण आप अपनी कुंजी से GET के ज़रिए प्राप्त करते हैं, और वह कॉल पहले से ही आपके अपने प्राधिकरण गेट से होकर गुज़रती है। इसलिए जोखिम की सतह पहचानकर्ता स्तर पर ही रहती है। दो फ़ील्ड जानबूझकर अनुपस्थित हैं: बोली लगाने वाली कंपनी की पहचान (ब्लाइंड बोलियाँ पैनल में एक उपनाम के तहत दिखती हैं; पहचान को वेबहुक में डालना उस गोपनीयता को दूसरे चैनल से भेद देता) और आरक्षण के संपर्क विवरण (व्यक्तिगत डेटा को एक अतिरिक्त चैनल से ले जाने की कोई ज़रूरत नहीं)।
इवेंट नाम स्थिर (फ़्रीज़) हैं। यदि किसी नाम का अर्थ बदलता है, तो एक नया नाम खोला जाता है और पुराना नाम एक अप्रचलन (deprecation) विंडो तक चलता रहता है। पेलोड में नया फ़ील्ड जोड़ने से कॉन्ट्रैक्ट संस्करण नहीं बढ़ता — उपभोक्ता को उन फ़ील्ड को अनदेखा करना होगा जिन्हें वह नहीं जानता।
GET /api/common/integration-webhooks — लेजर, साथ में इवेंट कैटलॉग, सीमाएँ और हेडर नाम। हर पंक्ति अपना म्यूट कारण और 7 दिनों का डिलीवरी सारांश रखती है।
POST /api/common/integration-webhooks — 201 + { webhook, secret, shown_once: true }। सीक्रेट केवल यहीं दिखाई देता है।
PATCH /api/common/integration-webhooks/{uuid} — नाम / पता / इवेंट / सक्रिय फ़्लैग। सीक्रेट को नहीं छूता।
DELETE /api/common/integration-webhooks/{uuid} — इसे हटाता है: पंक्ति सॉफ़्ट-डिलीट होती है (इतिहास क्वेरी योग्य रहता है) और लंबित डिलीवरी रद्द कर दी जाती हैं।
POST /api/common/integration-webhooks/{uuid}/rotate-secret — 201 + एक नया सीक्रेट। पुराना मान उसी क्षण काम करना बंद कर देता है।
POST /api/common/integration-webhooks/{uuid}/test — एक ping इवेंट — असली हस्ताक्षर, असली रास्ता, असली पुनः प्रयास शेड्यूल।
GET /api/common/integration-webhooks/{uuid}/deliveries — सबसे हाल की डिलीवरी: स्थिति, प्रयास संख्या, HTTP कोड, अवधि, त्रुटि टैग।
POST /api/common/integration-webhooks/deliveries/{uuid}/replay — एक डिलीवरी को फिर से भेजता है: event_id सुरक्षित (अपरिवर्तित) रहता है, डिलीवरी 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 के साथ स्वयं का परीक्षण करते हैं: वैध हस्ताक्षर, छेड़छाड़ की गई बॉडी, गलत सीक्रेट, विंडो से बाहर का टाइमस्टैम्प, विकृत हेडर, री-सीरियलाइज़ेशन का जाल और दोनों प्रकार की पुनरावृत्ति (वही डिलीवरी / वही तथ्य)। सत्यापनकर्ता ठीक उसी कोड का समकक्ष है जिसका हम स्वयं उपयोग करते हैं — जो कॉन्ट्रैक्ट हम प्रकाशित करते हैं, उसका उपभोग हम खुद करते हैं।
कच्ची (RAW) बॉडी का सत्यापन करें — हस्ताक्षर बाइट्स पर गणना किया जाता है। बॉडी को डिकोड करके फिर से सीरियलाइज़ करना (JSON.stringify(req.body), json_encode($request->all())) उसी डेटा को अलग बाइट्स में बदल देता है और हस्ताक्षर मेल खाना बंद कर देता है। Node में जाल संख्या फ़ॉर्मैटिंग है (वायर पर 1.50 बन जाता है 1.5; बड़े पूर्णांक सटीकता खो देते हैं), PHP में यह कैरेक्टर एस्केपिंग है (/ बन जाता है \/, İ बन जाता है \u0130)। Express में express.raw और Laravel में $request->getContent() का उपयोग करें। रिसीवर लिखते समय यही सबसे आम गलती है।
टाइमस्टैम्प जाँचें — t हस्ताक्षर के भीतर है। केवल हस्ताक्षर का सत्यापन करने से कोई भी व्यक्ति जिसने एक वैध अनुरोध पकड़ लिया हो, उसे घंटों बाद दोहरा (replay) सकता है, और रिसीवर उसे सत्यापित इवेंट मान लेगा। ऐसा कोई भी अनुरोध छोड़ दें जहाँ |now − t| > tolerance हो, भले ही हस्ताक्षर सही हो। अनुशंसित विंडो 300 सेकंड है।
स्थिर समय (constant time) में तुलना करें — hash_equals / timingSafeEqual। == से तुलना करने पर हमलावर हस्ताक्षर का अनुमान बाइट दर बाइट लगा सकता है।
डुप्लिकेट event_id के आधार पर हटाएँ, id के आधार पर नहीं — event_id तथ्य की पहचान करता है: एक ही इवेंट पाने वाले दो सब्सक्राइबर के लिए यह एक जैसा होता है, और replay पर अपरिवर्तित रहता है। id (= X-Logistivo-Delivery) डिलीवरी की पहचान करता है और replay पर बदल जाता है। "क्या मैंने इसे पहले ही संभाल लिया है" का उत्तर event_id से दें; id से उत्तर देने पर replay वही काम दो बार चला देता है।
डिलीवरी, पुनः प्रयास और म्यूट करना
आपका रिसीवर हमेशा चालू नहीं रहेगा। यह रेल इसे मानकर चलती है: अस्थायी विफलता पुनः प्रयास शेड्यूल में जाती है, स्थायी विफलता सब्सक्रिप्शन को म्यूट कर देती है — और म्यूट करने का कारण हमेशा दर्ज किया जाता है।
म्यूट करने का कारण मशीन-पठनीय और स्थिर है (delivery_failures, endpoint_gone, unsafe_target, key_revoked, by_user) और पैनल तथा `lg webhooks list` दोनों में दिखाई देता है। बिना कारण के म्यूट करने पर "कुछ भी क्यों नहीं आ रहा" का कोई उत्तर नहीं रहता। फिर से सक्षम करने पर काउंटर और मुहर (stamp) रीसेट हो जाते हैं।
पता आप लिखते हैं; अनुरोध हमारा सर्वर करता है। बिना गेट के, कोई टेनेंट जो क्लाउड मेटाडेटा पता डाल दे, हमसे हमारे अपने नेटवर्क के भीतर से अनुरोध करवा सकता था। इसलिए पते की जाँच पंजीकरण के समय भी होती है और हर एक डिलीवरी पर भी:
टाइमआउट — कुल 8 s, कनेक्ट करने के लिए 4 s — धीमे रिसीवर को किसी वर्कर को घेरकर नहीं रखना चाहिए। काम को कतार में डालें और तुरंत 2xx लौटाएँ।
पुनः प्रयास शेड्यूल — 60 · 300 · 1800 · 7200 · 21600 सेकंड → 6 प्रयास, लगभग 8.6 घंटे की विंडो।
एकमात्र स्थायी विफलता: 410 Gone — इसका अर्थ है "मुझे हटा दो": कोई पुनः प्रयास नहीं, सब्सक्रिप्शन तुरंत म्यूट हो जाता है। हस्ताक्षर विफलता के लिए कभी भी 410 न लौटाएँ।
बाकी हर विफलता — उन सभी का पुनः प्रयास होता है, 4xx सहित। किसी व्यावसायिक इवेंट को खोना कुछ अतिरिक्त अनुरोधों से अधिक महँगा है: जब कोई WAF नियम अपडेट हो रहा हो और रिसीवर 403 लौटा रहा हो, तो 4xx को स्थायी मानने वाली रेल पर "इनवॉइस जारी हुआ" इवेंट चुपचाप खो जाता।
Retry-After — 429 और 503 पर इसका पालन होता है (अधिकतम 6 घंटे)।
रीडायरेक्ट — इनका पालन नहीं किया जाता। 302 के ज़रिए किसी आंतरिक पते पर कूदना पते के गेट को दूसरे रास्ते से भेद देता।
स्वचालित म्यूट — लगातार 10 डिलीवरी के सभी प्रयास समाप्त हो जाने के बाद। 410, असुरक्षित लक्ष्य और जुड़ी हुई इंटीग्रेशन कुंजी का रद्द होना तुरंत म्यूट कर देते हैं।
केवल https, केवल पोर्ट 443/8443, एम्बेडेड क्रेडेंशियल (https://user:pass@…) अस्वीकार;
localhost, एकल-लेबल नाम और .internal / .local / .svc जैसे आंतरिक प्रत्यय अस्वीकार किए जाते हैं — इरादे को रिज़ॉल्यूशन का परिणाम देखने से पहले ही अस्वीकार कर दिया जाता है, ताकि split-horizon DNS गेट को भेद न सके;
IP लिटरल और DNS रिज़ॉल्यूशन के सभी रिकॉर्ड सार्वजनिक होने चाहिए। यदि कोई नाम सार्वजनिक और निजी दोनों पतों पर रिज़ॉल्व होता है, तो कोई हमसे नहीं पूछता कि कौन-सा चुनें → नाम सीधे अस्वीकार कर दिया जाता है;
डिलीवरी के समय पता एक बार रिज़ॉल्व किया जाता है और कनेक्शन सत्यापित पते पर पिन कर दिया जाता है: DNS rebinding की खिड़की बंद रहती है;
रिसीवर की प्रतिक्रिया बॉडी कभी कहीं संग्रहीत नहीं की जाती (केवल स्टेटस कोड, अवधि और एक छोटा त्रुटि टैग) — इसलिए "पढ़ने" का रास्ता, जिसके लिए पते के गेट में छेद वास्तव में मूल्यवान होता है, बंद रहता है।
"निजी पतों की अनुमति दें" जैसा कोई कॉन्फ़िगरेशन स्विच जानबूझकर नहीं रखा गया है: ऐसा स्विच किसी दिन गलती से चालू रह जाता है।
केवल एक बार लौटाया जाता है — सब्सक्रिप्शन बनाते समय और rotate-secret पर। यह सर्वर पर एन्क्रिप्ट करके संग्रहीत होता है और कभी वापस पढ़ा नहीं जा सकता; "फिर से दिखाएँ" जैसा कुछ नहीं है।
lg इसे स्क्रीन पर प्रिंट करता है और वहीं छोड़ देता है — यह इसे किसी कॉन्फ़िगरेशन या कैश फ़ाइल में नहीं लिखता।
यदि यह खो जाए तो आप इसे रोटेट करते हैं; पुराना मान उसी क्षण काम करना बंद कर देता है। बिना रुकावट के बदलाव के लिए, संक्रमण के दौरान आपके रिसीवर को दोनों सीक्रेट आज़माने चाहिए।
पता बदलने से सीक्रेट पर कोई असर नहीं पड़ता: "URL बदल गया" जैसा नियमित रखरखाव प्राप्त करने वाली ओर के सत्यापन को नहीं तोड़ना चाहिए।
स्वास्थ्य और स्थिति: किसी को भी आपसे पहले एक चुप पड़े ब्रिज का पता नहीं चलना चाहिए
कोई इंटीग्रेशन ब्रिज शायद ही कभी शोर मचाकर बंद होता है। आमतौर पर वह देर रात चुपचाप शांत हो जाता है: कोई टोकन समाप्त हो जाता है, जिस व्यक्ति की ओर से कुंजी चलती है वह टीम छोड़ देता है, कोई स्कोप सीमित कर दिया जाता है, या प्राप्त करने वाला एंडपॉइंट 403 लौटाने लगता है। सबसे पहले ध्यान देने वाला लगभग हमेशा ग्राहक होता है। lg status इसी क्रम को उलटने के लिए है।
एक ही कमांड दो प्रश्नों का उत्तर एक साथ देती है, क्योंकि आउटेज के दौरान दोनों एक ही क्षण पूछे जाते हैं: क्या प्लेटफ़ॉर्म चालू है, और क्या मेरा ब्रिज स्वस्थ है। प्लेटफ़ॉर्म वाली पंक्ति बिना टोकन के काम करती है — विफलता के दौरान टोकन स्वयं पहला संदिग्ध होता है, और स्थिति के प्रश्न को उससे बाँधने पर ठीक उसी समय आपको कोई उत्तर नहीं मिलता जब आपको उसकी ज़रूरत होती है।
स्वास्थ्य सारांश कोई नया लेजर नहीं रखता; यह तीन मौजूदा स्रोतों को एक ही वाक्य में समेटता है: दैनिक उपयोग काउंटर (आपने कितनी कॉल कीं और कितनी विफल हुईं), अनुरोध लेजर (कौन-सा अनुरोध, कब, और क्यों अस्वीकार हुआ) और आउटगोइंग वेबहुक डिलीवरी लेजर (क्या इवेंट रिसीवर तक पहुँचा)। त्रुटि दर हमेशा दैनिक काउंटर से पढ़ी जाती है; विवरण वाले लेजर की एक सीमा है और सीमा पूरी होने पर वह यह बात साफ़-साफ़ बताता है।
यही सारांश पैनल में भी दिखाई देता है: Settings › Integration › Keys के अंतर्गत हर पंक्ति एक बैज रखती है और उसके नीचे कारण। सीमाएँ (थ्रेशोल्ड) क्लाइंट की ओर गणना नहीं की जातीं; सर्वर ने जो भी स्तर तय किया, वही पैनल और lg status दोनों दिखाते हैं, इसलिए दोनों स्क्रीन एक ही कुंजी के बारे में कभी अलग-अलग बातें नहीं कह सकतीं।
आपके वॉचडॉग को किसी टोकन की ज़रूरत नहीं है। एंडपॉइंट केवल स्थिति वाले शब्द लौटाता है; इसमें कोई संस्करण, होस्ट नाम, कतार का नाम, जॉब की संख्या, त्रुटि पाठ या ग्राहक डेटा नहीं होता — और हो भी नहीं सकता।
स्वास्थ्य सारांश प्रति अनुरोध क्वेरी की एक स्थिर संख्या से तैयार होता है; क्वेरी की संख्या कुंजियों की संख्या के साथ नहीं बढ़ती। विवरण के लिए, उस कुंजी के हाल के अनुरोध lg logs से और आउटगोइंग ब्रिज को lg webhooks list से पढ़ें।
स्वस्थ — कोई मापी गई खराबी नहीं और हमारे पास सफलता का प्रमाण है: लेजर में एक सफल कॉल, या ऐसा ट्रैफ़िक जो काउंटर में त्रुटि-मुक्त रहा।
ध्यान दें — कुछ टूटना शुरू हो गया है: त्रुटि दर या लगातार विफलताओं की शृंखला किसी सीमा को पार कर गई, अनुरोध गेट पर अस्वीकार हो रहे हैं, कुंजी समाप्ति के करीब है, या नियमित रूप से बात करने वाला कोई ब्रिज चुप हो गया।
विफल हो रहा — ब्रिज इस समय काम नहीं कर रहा: टोकन अनजाने में रद्द हो गया, किसी बंद कुंजी को अब भी कॉल किया जा रहा है, लगातार पाँच विफलताएँ हैं, त्रुटि दर पचास प्रतिशत से ऊपर है, या कोई वेबहुक सब्सक्रिप्शन म्यूट हो गया।
बंद — कुंजी जानबूझकर बंद की गई और कोई उसे कॉल नहीं कर रहा। यह एक निर्णय है, खराबी नहीं — और इसे लाल रंग में नहीं दिखाया जाता।
कोई डेटा नहीं — कोई मापन नहीं है: कुंजी को कभी कॉल नहीं किया गया, या मापन स्वयं विफल हो गया। इनमें से कोई भी हरा नहीं है।
कोई झूठा हरा नहीं। स्वस्थ बैज के लिए सफलता का मापा हुआ प्रमाण चाहिए; जिस कुंजी को कभी कॉल नहीं किया गया, वह कभी हरी नहीं होती, क्योंकि एक भी मापन यह नहीं दिखाता कि वह काम करती है।
कोई झूठा लाल नहीं। जिन कुंजियों को आपने जानबूझकर बंद किया, वे "बंद" के रूप में दिखती हैं। सब कुछ लाल रंग में दिखाने से लाल का कोई अर्थ नहीं रह जाता; बंद कुंजी केवल तभी लाल होती है जब बंद होने के बाद भी उसे कॉल किया जा रहा हो — और तब सचमुच कोई ब्रिज टूटा होता है।
माप न पाना और डेटा न होना एक ही बात नहीं है। यदि कोई क्वेरी सर्वर की ओर विफल होती है, तो पंक्ति चुपचाप शून्य नहीं दिखाती; वह बताती है कि मापन नहीं लिया जा सका।
चुप्पी की सूचना हमेशा दी जाती है, लेकिन उसे कभी आँख मूँदकर चेतावनी में नहीं बदला जाता। महीने के अंत में चलने वाले ब्रिज का तीस घंटे चुप रहना सामान्य है; जो ब्रिज पिछले सात दिनों में से कम से कम पाँच दिन बोला हो, उसका चुप हो जाना खराबी है। लय मापी जाती है, मानी नहीं जाती।
स्थिति क्वेरी स्वयं स्वास्थ्य के आँकड़ों को दूषित नहीं करती। lg status द्वारा की गई कॉल अनुरोध लेजर में दिखाई देती हैं, लेकिन स्वास्थ्य की गणना से बाहर रखी जाती हैं — अन्यथा आपकी अपनी सफल स्थिति क्वेरी विफलताओं की शृंखला को रीसेट कर देती और ठीक वही खराबी छिपा देती जिसे दिखाने के लिए यह स्क्रीन है।
हर पंक्ति मापी जाती है: डेटाबेस पर एक असली क्वेरी चलाई जाती है, कमांड कैटलॉग वास्तव में बनाया जाता है, कतार वर्कर का लाइव रिकॉर्ड वास्तव में पढ़ा जाता है। कुछ भी माना नहीं जाता।
प्रतिक्रिया स्वयं भी एक मापन है: यदि आप बॉडी पढ़ सकते हैं, तो वेब स्तर चालू है।
शीर्ष स्तर केवल आवश्यक घटकों से निकाला जाता है। जब कतार रुकती है तो उत्तर degraded होता है, down नहीं — एक सिंक्रोनस API कॉल को कतार की ज़रूरत नहीं होती, और प्लेटफ़ॉर्म को down घोषित करना झूठा अलार्म होगा।
जब कतार की स्थिति मापी नहीं जा सकती, तो शीर्ष स्तर को अछूता छोड़ दिया जाता है: न जानना यह मापने के समान नहीं है कि कुछ टूटा हुआ है।
यदि प्लेटफ़ॉर्म down है, तो एंडपॉइंट 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 · आइडेम्पोटेंट 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 · नहीं — भूमिका गेट, या लिखने वाली कमांड पर read स्कोप वाली कुंजी।
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 · हाँ — वही आइडेम्पोटेंसी कुंजी रखते हुए एक्सपोनेंशियल बैकऑफ़ के साथ; कुंजी लॉक नहीं हुई थी।
401 unauthenticated — टोकन समाप्त हो गया या रद्द कर दिया गया। दोबारा प्रयास करने से मदद नहीं मिलेगी; टोकन बदलना होगा।
429 rate_limited — इस टोकन पर रेट लिमिट लागू है। प्रतिक्रिया में हमेशा Retry-After और retry_after, limit तथा bucket वाली बॉडी होती है; कोई निश्चित विलंब गढ़ने के बजाय उसका पालन करें। lg प्रतीक्षा करता है और तीन बार तक पुनः प्रयास करता है, फिर एग्ज़िट कोड 5 के साथ बाहर निकलता है।
5xx server_error / नेटवर्क त्रुटि — एक्सपोनेंशियल बैकऑफ़ और वही आइडेम्पोटेंसी कुंजी के साथ पुनः प्रयास करें। कुंजी बदलने से वह काम फिर से चलता है जिसे सर्वर शायद पहले ही पूरा कर चुका हो। lg तीन बार पुनः प्रयास करता है (1 s, 2 s, 4 s), फिर error_code network_error या server_error के साथ एग्ज़िट कोड 6 से बाहर निकलता है।
स्थिरता का वादा
किसी इंटीग्रेशन कॉन्ट्रैक्ट में सबसे महँगा प्रश्न है “क्या आज मैं जो कोड लिखता हूँ, वह कल भी चलेगा?” एक संख्या इसका उत्तर देती है: कैटलॉग में contract_version, और हर प्रतिक्रिया पर X-Contract-Version हेडर। यह ठीक एक प्रश्न का उत्तर देती है — क्या पहले लिखा गया कोड बिना बदलाव के अब भी चलता है? यदि संख्या नहीं बढ़ी, तो हाँ। यदि बढ़ी, तो नहीं: जिस चीज़ पर आप निर्भर थे, उसे हटाया या सीमित किया गया।
क्योंकि घोषणा कुछ भी नहीं हटाती: आपका मौजूदा कोड अगले दिन भी ठीक पहले की तरह चलता है। घोषणा पर संस्करण बढ़ाने से एक बदलाव के लिए दो संकेत निकलते और आपको पहले संकेत को अनदेखा करने की आदत पड़ जाती — जिससे वह संकेत कमज़ोर होता जो वास्तव में मायने रखता है। घोषणा पहले से ही उस कॉल के साथ आती है जो आप कर रहे हैं: कैटलॉग पंक्ति पर deprecated_at और replaced_by, उस कमांड की प्रतिक्रिया पर X-Deprecated हेडर और एक deprecated ब्लॉक, और यदि आप lg उपयोग करते हैं तो stderr पर एक-पंक्ति की चेतावनी। कुछ हटने वाला है, यह जानने के लिए आपको कुछ भी करने की ज़रूरत नहीं; यह पहले से आपके लॉग में है।
घोषणा और हटाने के बीच कम से कम दो कैलेंडर तिमाहियाँ बीतती हैं। पूरी विंडो के दौरान पुरानी कमांड उत्तर देती रहती है, और हर कॉल पर चेतावनी देती है। जब कोई CLI नाम सेवानिवृत्त होता है, तो उसका उत्तराधिकारी उस नाम को alias के रूप में अपना लेता है: विंडो के दौरान पुराना नाम पुरानी कमांड तक पहुँचता है, और जिस दिन उसे हटाया जाता है, वही कॉल नई कमांड पर पहुँचती है — बिना आपके कोई क्लाइंट रिलीज़ भेजे।
preview_invoice → get_invoice (3 सितंबर 2026 को घोषित)। get_invoice वही preview ब्लॉक लौटाती है और साथ में लाइन आइटम, कर का ब्योरा, दर्ज भुगतान, शेष राशि और आपकी अपनी ERP कुंजी (external_ref) से संबोधन जोड़ती है। preview_invoice काम करती रहती है, और lg invoices preview भी — दोनों चेतावनी देती हैं।
कोई बदलाव नहीं — नई कमांड · नया वैकल्पिक पैरामीटर · नया प्रतिक्रिया फ़ील्ड · नई त्रुटि कुंजी · नया एंडपॉइंट — कुछ न करें। जिन फ़ील्ड को आप नहीं जानते, उन्हें अनदेखा करना अनिवार्य है; अज्ञात फ़ील्ड पर विफल होने वाला पार्सर मानक के अनुरूप नहीं है।
कोई बदलाव नहीं — अप्रचलन की घोषणा: सूचना कि कोई कमांड हटने वाली है — आपका कोड चलता रहता है। अपने कैलेंडर में एक कार्य जोड़ लें — विंडो कम से कम 6 महीने की है।
बढ़ता है — कमांड हटाना · पुराना CLI नाम सेवानिवृत्त करना · प्रतिक्रिया फ़ील्ड हटाना · वैकल्पिक पैरामीटर को अनिवार्य बनाना · enum को सीमित करना — इसका अर्थ है कि आप विंडो चूक गए; सूचना आप तक तीन अलग-अलग जगहों पर पहुँची थी।
किसी कमांड का API नाम (जैसे list_loads) हमेशा के लिए स्थिर है; HTTP कॉल में आप यही नाम उपयोग करते हैं।
error_code (ट्रांसपोर्ट) और error_key (व्यावसायिक नियम) स्थिर स्ट्रिंग हैं। नए आ सकते हैं — जो कुंजी आपको शब्दकोश में न मिले, उसे टूटन नहीं, बल्कि सामान्य विफलता मानें।
HTTP स्थिति और बॉडी के status फ़ील्ड के बीच का मेल तय है।
संस्करण संख्या कभी घटती नहीं, और हर प्रतिक्रिया पर पढ़ी जा सकती है — बिना बॉडी वाले 304 और 429 सहित।
त्रुटि और विवरण का पाठ। यह स्थानीयकृत है और बिना सूचना के बदलता है; संदेश के पाठ पर शाखा बनाना समर्थित नहीं है।
उन फ़ील्ड की अनुपस्थिति जिन्हें आप नहीं जानते। फ़ील्ड जोड़ने से संस्करण नहीं बढ़ता।
व्यावसायिक कुंजी के रूप में ऑटो-इंक्रीमेंट id। अपनी कुंजी external_ref के साथ रखें।
क्लास नामों से निकली गतिशील त्रुटि कुंजियाँ; वे कॉन्ट्रैक्ट का हिस्सा नहीं हैं।
कमांड पहचान तालिका
नीचे दी गई तालिका हाथ से नहीं लिखी गई है: यह पृष्ठ परोसे जाने पर हर बार लाइव कमांड रजिस्ट्री से जनरेट होती है। सर्वर पर जोड़ी गई कमांड यहाँ अपने आप दिखाई देती है। "गेट" कॉलम बताता है कि कोई कमांड पुष्टि माँगती है या नहीं और उसका प्रभाव पलटा जा सकता है या नहीं; "भूमिकाएँ" कॉलम बताता है कि किन खाता प्रकारों को वह अपने कैटलॉग में मिलेगी। बैज उन कमांड को चिह्नित करते हैं जिन्हें manager-स्तर की कुंजी चाहिए, जो कोई फ़ाइल लेती हैं और जो केवल lg से चलती हैं।
कमांड कार्य के अनुसार समूहित हैं, हर कार्य का अपना पेज है। किसी कार्य को चुनें, उसकी कमांड तालिका खुल जाएगी।
API नाम (list_loads) स्थिर है और नहीं बदलेगा; HTTP कॉल में आप यही नाम उपयोग करते हैं। CLI पहचान (loads list) संस्करण नीति के अधीन है: घोषित होने के बाद यह केवल संस्करण वृद्धि और एक माइग्रेशन विंडो के साथ बदलती है, जिसके दौरान कैटलॉग पुरानी जोड़ी को alias के रूप में परोसता है। यहाँ के विवरण हर कमांड के अपने रिकॉर्ड से आते हैं और छोटे किए गए हैं — पूरे पाठ, पैरामीटर प्रकारों और enum मानों के लिए, कैटलॉग एंडपॉइंट पढ़ें या lg help चलाएँ। केवल एफ़िलिएट के लिए बनी कमांड यहाँ सूचीबद्ध नहीं हैं; एफ़िलिएट खाता उन्हें अपने कैटलॉग में देखता है।
लोड और ट्रैकिंग — लोड बनाना, पक्ष, दस्तावेज़, ट्रैकिंग लिंक, डिलीवरी हस्ताक्षर, ETA और अपवाद। 115 कमांड — /hi/developers/cli/loads
सीमा और सीमा शुल्क — सीमा तैयारी जाँच, सीमा और बंदरगाह पर प्रतीक्षा, निर्यात दस्तावेज़, U-ETDS सूचना। 42 कमांड — /hi/developers/cli/border
माँग और बोलियाँ — परिवहन माँग खोलना, बोली माँगना और देना, निविदाएँ, आपके नेटवर्क के वाहक। 42 कमांड — /hi/developers/cli/quotes
रेट कार्ड और बिक्री कोटेशन — तय रेट कार्ड, ऑफ़र वॉटरफ़ॉल और ग्राहकों को बिक्री कोटेशन। 57 कमांड — /hi/developers/cli/pricing
फ़्लीट और ड्राइवर — ड्राइवर, वाहन, ख़र्च रसीदें, ड्राइवर खाते, यात्रा योजना और शेंगेन दिन। 115 कमांड — /hi/developers/cli/fleet
गोदाम और स्टॉक — गोदाम, आरक्षण, डॉक अपॉइंटमेंट, गेट स्क्रीन, उत्पाद, स्टॉक और पैलेट। 69 कमांड — /hi/developers/cli/warehouse
लेखा और बिलिंग — चालान, ख़रीद चालान की जाँच, Paraşüt, जर्नल प्रविष्टियाँ, वसूली और भुगतान, मार्जिन। 95 कमांड — /hi/developers/cli/finance
संदेश और ईमेल — लोड चैट, सीधे संदेश, ईमेल ड्राफ़्ट और इनबॉक्स, सूचनाएँ। 58 कमांड — /hi/developers/cli/messages
टैरिफ़ और व्यापार उपाय — HS कोड खोज, आयात शुल्क, एंटी-डंपिंग उपाय, कार्बन रिपोर्ट। 20 कमांड — /hi/developers/cli/tariffs
कंपनियाँ और टीम — कंपनी निर्देशिका, संबंध और दस्तावेज़, सहायक कंपनियाँ, टीम सदस्य और आमंत्रण। 65 कमांड — /hi/developers/cli/contacts
ऑटोमेशन और रिपोर्ट — ऑटोमेशन नियम, कस्टम रिपोर्ट, Excel और PDF फ़ाइलें, कार्य योजनाएँ। 27 कमांड — /hi/developers/cli/automation
खाता और इंटीग्रेशन — खाता और भाषा सेटिंग, इंटीग्रेशन कुंजियाँ, पैकेज, क्रेडिट और वॉलेट। 16 कमांड — /hi/developers/cli/account
ERP और CRM इंटीग्रेशन — पहचान: कोई सर्विस खाता नहीं, बल्कि एक वास्तविक उपयोगकर्ता
ERP या CRM, Logistivo से एक वास्तविक कंपनी उपयोगकर्ता के रूप में जुड़ता है, जिसके पास पैनल से बनाया गया व्यक्तिगत एक्सेस टोकन होता है। कोई कृत्रिम सर्विस खाता — बिना कंपनी, स्कोपिंग से मुक्त, जिसकी कोई ज़िम्मेदारी न ले — कभी नहीं बनाया जाता।
यह आर्किटेक्चर है, पसंद नहीं। मल्टी-टेनेंट अलगाव पूरी तरह उपयोगकर्ता की कंपनी पर टिका है; बिना कंपनी वाली पहचान के लिए अलगाव का दायरा निष्क्रिय हो जाता है, और उस टोकन पर एक गलत क्वेरी ऐसा डेटा पढ़ लेती है जो उसका नहीं है। दूसरा कारण ऑडिट है: लेजर का उपयोगकर्ता कॉलम "इसे किसने चलाया" को एक व्यक्ति से जोड़ता है; सर्विस खाता उस कॉलम को निरर्थक बना देता है और इनवॉइस जारी करने वाले इंटीग्रेशन को बिना मालिक के छोड़ देता है। तीसरा कारण रद्द करना है: यदि टोकन किसी व्यक्ति का है, तो उस व्यक्ति के जाने पर इंटीग्रेशन चुप हो जाता है। बिना मालिक का ब्रिज वही ब्रिज है जो वर्षों तक चुपचाप लिखता रहता है।
व्यवहार में: कंपनी पैनल में एक सामान्य उपयोगकर्ता बनाती है (उदाहरण के लिए "ERP Bridge", जिसका स्वामी कोई नामित कर्मचारी हो), उसे एक सीमित भूमिका देती है, उस उपयोगकर्ता के सत्र से एक टोकन बनाती है और उसे ERP में रखती है।
वह उपयोगकर्ता अनुमति प्रणाली में दिखाई देता है, उसके अधिकार घटाए जा सकते हैं, और उसका टोकन अलग से रद्द किया जा सकता है। वर्जित खाता बनाना नहीं है — वर्जित है ऐसा खाता बनाना जो किसी टेनेंट से बँधा न हो।
प्रति टोकन एक इंटीग्रेशन। यदि दो सिस्टम एक टोकन साझा करते हैं, तो रद्द करने की बारीकी खत्म हो जाती है: CRM को काटने का मतलब ERP को भी काटना होता है।
ERP और CRM इंटीग्रेशन — संस्करण प्रबंधन और अप्रचलन
कैटलॉग प्रतिक्रिया एक contract_version पूर्णांक रखती है; कमांड पंक्तियाँ since, deprecated_at और replaced_by रखती हैं। कॉन्ट्रैक्ट संस्करण केवल तोड़ने वाले (breaking) बदलावों पर बढ़ता है।
संस्करण इन पर नहीं बढ़ता: नई कमांड, नया वैकल्पिक पैरामीटर, प्रतिक्रिया में नया फ़ील्ड। उपभोक्ता को उन फ़ील्ड को अनदेखा करना होगा जिन्हें वह नहीं जानता; अज्ञात फ़ील्ड पर त्रुटि देने वाला क्लाइंट अनुरूप नहीं है।
संस्करण इन पर बढ़ता है: किसी कमांड को हटाना या उसका नाम बदलना, कोई प्रतिक्रिया फ़ील्ड हटाना, वैकल्पिक पैरामीटर को अनिवार्य बनाना, enum को सीमित करना। पुराना रूप deprecated_at और replaced_by के साथ कम से कम दो कैलेंडर तिमाहियों (6 महीने) तक जीवित रहता है।
अप्रचलन की घोषणा कैटलॉग में होती है, केवल किसी 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= किसी पुराने alias डोमेन को वर्तमान कमांड पर रिज़ॉल्व करता है।
जो क्लाइंट संस्करण 1 समझता है और उससे बड़ी संख्या देखता है, उसे चेतावनी लॉग करनी चाहिए और चलते रहना चाहिए; lg ठीक यही करता है। लागू सेवानिवृत्तियाँ ऊपर स्थिरता के वादे में सूचीबद्ध हैं।
ERP और CRM इंटीग्रेशन — स्थिर पहचानकर्ता: अपने ERP को कभी भी ऑटो-इंक्रीमेंट id कुंजी के रूप में न दें
आंतरिक ऑटो-इंक्रीमेंट id अपारदर्शी और टेनेंट-सीमित हैं: किसी दूसरी कंपनी की वैध id आपको डेटा नहीं, बल्कि "नहीं मिला" लौटाती है। लेकिन अपारदर्शी होना उन्हें व्यावसायिक कुंजी नहीं बनाता। ERP अपने रिकॉर्ड में जो संग्रहीत करता है, वह एक व्यावसायिक कुंजी होनी चाहिए।
लोड: code (ग्राहक कोड, उदाहरण: FSK2158)। loads get पहले से ही code से काम करता है।
देश: ISO 3166-1 alpha-2। countries search कोड लौटाता है।
HS / टैरिफ़: स्वयं कोड — नामावली पहले से ही सार्वभौमिक है।
इनवॉइस: जारी होने के बाद इनवॉइस नंबर। ड्राफ़्ट के पास केवल सतही id होती है, और ड्राफ़्ट id व्यावसायिक कुंजी नहीं है — ERP को अपना संदर्भ रखना चाहिए और ड्राफ़्ट id कभी संग्रहीत नहीं करनी चाहिए।
उत्पाद, गोदाम, संपर्क: आज केवल सतही id। नई कमांड के लिए नियम स्पष्ट है: सतही id लौटाने वाली हर कमांड टेनेंट की अपनी व्यावसायिक कुंजी (SKU, कोड, कर संख्या) भी लौटाती है, ताकि ERP अपनी ओर मिलान कर सके।
ERP और CRM इंटीग्रेशन — पेजिनेशन, फ़िल्टरिंग और इंक्रीमेंटल सिंक
सूची कमांड limit लेती हैं और count लौटाती हैं। रात के सिंक के लिए कॉन्ट्रैक्ट निम्नलिखित के लिए प्रतिबद्ध है; जिस सूची कमांड ने इसे अपना लिया है, वह अपने JSON Schema में cursor और updated_since घोषित करती है, और जब तक ऐसा नहीं होता, उसे एक छोटी विंडो मानें (अधिकतम 20 पंक्तियाँ, कोई कर्सर नहीं)।
अनुरोध: limit (1..प्रति-कमांड अधिकतम सीमा) और cursor (अपारदर्शी, केवल आगे की ओर, सर्वर द्वारा हस्ताक्षरित)। offset का उपयोग नहीं होता — लाइव तालिका में 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 के साथ दूसरा create डुप्लिकेट बनाने के बजाय अस्वीकार कर दिया जाता है, और list/get उसे लौटाते हैं ताकि आप अपनी ओर रिकॉर्ड का मिलान कर सकें।
ERP और CRM इंटीग्रेशन — रेट लिमिट
लिमिट की कुंजी टोकन है, IP नहीं: ERP एक ही NAT के पीछे से आता है, और IP-आधारित लिमिट पूरी कंपनी को एक उपयोगकर्ता गिन लेती। दो कुंजियों वाले दो इंटीग्रेशन कभी एक-दूसरे का कोटा नहीं खाते — "प्रति कुंजी एक इंटीग्रेशन" का यह दूसरा कारण है।
बिना प्रमाणीकरण वाली खोज (public/cli/catalog): प्रति मिनट 30। यह एक शब्दकोश है, डेटा स्रोत नहीं; अपना ब्रिज लिखते समय इसे एक बार पढ़ें, किसी प्रोडक्शन लूप में कभी नहीं।
कैटलॉग एंडपॉइंट (GET common/commands, GET common/commands/{name}): प्रति टोकन प्रति मिनट 120। कैटलॉग शायद ही कभी बदलता है और If-None-Match पर 304 उत्तर देता है; हर कमांड से पहले इसे दोबारा न खींचें — lg इसे एक घंटे के लिए कैश करता है।
पढ़ने वाली कमांड (read_only: true के साथ POST common/commands/{name}): प्रति टोकन प्रति मिनट 120।
लिखने वाली कमांड (read_only: false के साथ POST common/commands/{name}; अज्ञात नाम भी यहीं गिना जाता है): प्रति टोकन प्रति मिनट 30। लिखने के दुष्प्रभाव होते हैं; बेकाबू लूप का बिल बनता है।
क्रेडिट खर्च करने वाली कमांड (कैटलॉग पंक्ति में credit_cost शून्य नहीं है — उदाहरण के लिए tariffs inquiry और export-documents generate): असली सीमा क्रेडिट है, अनुरोधों की संख्या नहीं। 200 प्रतिक्रिया ने शायद कोई क्रेडिट खर्च किया हो।
प्रति कंपनी दैनिक सीमाएँ, पैनल के साथ साझा: आपकी कंपनी के बाहर के लोगों को ई-मेल या पुश भेजने वाली कमांड प्रतिदिन 300 आउटबाउंड सूचनाओं के कोटे से लेती हैं, और भुगतान वाली कंटेनर या जहाज़ ट्रैकिंग शुरू करना प्रतिदिन 100 के कोटे से। सीमा पार होने पर कमांड retry_after के साथ DAILY_LIMIT_REACHED उत्तर देती है; फ़ाइल अपलोड की अपनी अलग सीमाएँ हैं ("फ़ाइलें लेने वाली कमांड" देखें)।
429 हमेशा Retry-After और एक बॉडी { error_code: "rate_limited", retry_after, limit, bucket } रखता है; कोई निश्चित विलंब गढ़ने के बजाय उसका पालन करें। कैटलॉग वर्तमान संख्याएँ rate_limits के अंतर्गत प्रकाशित करता है।
ERP और CRM इंटीग्रेशन — जो हम नहीं करेंगे
यह अक्सर किसी कॉन्ट्रैक्ट का सबसे उपयोगी हिस्सा होता है: यह जानना कि क्या कभी नहीं आएगा, आपको उसके इर्द-गिर्द डिज़ाइन करने देता है।
कोई सर्विस खाता नहीं और कोई ऐसा प्रिंसिपल नहीं जो किसी टेनेंट से बँधा न हो।
API या चैट के ज़रिए कोई भुगतान, कार्ड नंबर या कानूनी सहमति नहीं। ये चरण व्यक्ति के ब्राउज़र में रहते हैं; कमांड आपको लिंक देती है।
कोई दूसरा रास्ता नहीं: कोई सीधा डेटाबेस एक्सेस नहीं, कोई शेल एक्सेस नहीं और कोई बल्क एंडपॉइंट नहीं जो एकल प्रवर्तन बिंदु को बायपास करे। भूमिका गेट, पुष्टि गेट, आइडेम्पोटेंसी और ऑडिट लेजर केवल वहीं लागू होते हैं।
त्रुटि संदेश के पाठ पर शाखा बनाना समर्थित नहीं है; पाठ स्थानीयकृत है और बिना सूचना के बदलता है।
offset पेजिनेशन नहीं।
अपने ERP में सतही id को व्यावसायिक कुंजी के रूप में उपयोग करना समर्थित नहीं है।
आउटगोइंग वेबहुक इस कॉन्ट्रैक्ट में ठूँसे नहीं गए हैं — लेकिन अब वे मौजूद हैं और इसी पृष्ठ पर प्रलेखित हैं (ऊपर वेबहुक खंड)। कैटलॉग एक पुल (pull) सतह है और इवेंट स्ट्रीम एक अलग कॉन्ट्रैक्ट है: इवेंट नाम और पेलोड स्कीमा अपने नियमों से संस्करणित होते हैं और कमांड कैटलॉग के कॉन्ट्रैक्ट संस्करण से बँधे नहीं हैं।
मशीन-पठनीय कैटलॉग
यह पृष्ठ लोगों के लिए लिखा गया था। किसी AI सहायक या स्वचालित क्लाइंट के लिए, यही जानकारी एक संरचित, बिना प्रमाणीकरण वाली प्रति के रूप में मौजूद है।
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 को किसी AI सहायक से जोड़ना एक अलग चैनल है, जिसका अपना पृष्ठ है:
कैटलॉग बिना प्रमाणीकरण का है; निष्पादन नहीं। किसी एजेंट की ओर से कमांड चलाने का कोई तरीका नहीं है — जो चलता है, वह हमेशा उपयोगकर्ता की अपनी पहचान होती है।
Logistivo पासवर्ड, सत्यापन कोड या एक्सेस टोकन कभी किसी चैट से होकर नहीं गुज़रता। ऐसा प्रवाह न बनाएँ जो इनमें से किसी को माँगे, बनाए या आगे भेजे।
कोई कमांड अपरिवर्तनीय है या नहीं, यह कैटलॉग में लिखा है। irreversible: true वाली कमांड पर कभी "चलो इसे आज़माते हैं" का सुझाव न दें।
जिन कमांड का credit_cost शून्य नहीं है (उदाहरण के लिए tariffs inquiry और export-documents generate), उनका परिणाम आर्थिक होता है; उन्हें किसी स्वचालित लूप में न बुलाएँ।
भुगतान, कार्ड नंबर और कानूनी सहमति कभी चैट या एजेंट से होकर नहीं जाते। इसके बजाय handoff-links generate से मिला लिंक दें; व्यक्ति वह चरण अपने ब्राउज़र में पूरा करता है।
उपयोगकर्ता की कुंजी से काम करने वाले एजेंट को सबसे पहले users get बुलाना चाहिए: यह भूमिका, कुंजी का एक्सेस स्तर, प्रभावी अनुमतियाँ और यह लौटाता है कि क्या कोई लंबित सहमति या फ़ोन सत्यापन लिखने को रोक रहा है — अस्वीकृतियाँ इकट्ठा करने के बजाय उनका पहले से अनुमान लगाएँ।
इस पृष्ठ का सादा-पाठ संस्करण /cli.md पर है; यदि आप HTML की तुलना में markdown को अधिक भरोसेमंद ढंग से पार्स करते हैं, तो उसका उपयोग करें।
मशीन-पठनीय परिभाषा: 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 एंडपॉइंट भी परिभाषा में हैं: इंक्रीमेंटल सिंक (updated_since + cursor + limit) वाले 10 सूची एंडपॉइंट और आपकी अपनी कुंजी (external_ref) स्वीकार करने वाले 7 लिखने वाले एंडपॉइंट। Logistivo की REST सतह इससे कहीं बड़ी है; बाकी को जानबूझकर बाहर रखा गया है। वे पेलोड उत्पाद का अपना कॉन्ट्रैक्ट हैं, और अनुमान से लिखा गया स्कीमा आपके जनरेट किए गए क्लाइंट को पहली ही कॉल पर तोड़ देता — और आप बग अपने कोड में खोजते, हमारे में नहीं।
परिभाषा पूछने वाले की भूमिका के लिए जनरेट होती है: किसी दूसरी भूमिका की कमांड कभी दस्तावेज़ में नहीं आती, क्योंकि परिभाषा एक कॉन्ट्रैक्ट है, शब्दकोश नहीं, और उसके भीतर की हर चीज़ उस टोकन से बुलाई जा सकनी चाहिए। बिना प्रमाणीकरण वाला संस्करण तीनों भूमिकाओं का संघ (union) है, और वहाँ हर ऑपरेशन 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 टोकन। read स्कोप वाली कुंजी केवल x-logistivo.read_only: true से चिह्नित ऑपरेशन बुला सकती है; लिखने का प्रयास पुष्टि गेट से पहले ही 403 लौटाता है, इसलिए read-only कुंजी को कभी 409 नहीं दिखता।
हर त्रुटि शाखा लिखी हुई है — हर ऑपरेशन 401/403/404/409/422/429/500 को अलग-अलग वर्णित करता है। 409 के दो अर्थ (पुष्टि आवश्यक / आइडेम्पोटेंसी टकराव) और 422 के दो अर्थ (स्कीमा त्रुटि / व्यावसायिक अस्वीकृति) दस्तावेज़ में अलग-अलग हैं, इसलिए आपका जनरेटर उन्हें एक ही शाखा में नहीं मिला देता।
कोई टाइमस्टैम्प नहीं — दस्तावेज़ में जनरेशन का समय नहीं होता। एक ही कैटलॉग एक जैसे बाइट्स बनाता है, यही कारण है कि ETag वास्तव में काम करता है और वर्ज़न कंट्रोल में कमिट की गई परिभाषा हर डाउनलोड पर 'बदली हुई' नहीं दिखती।
हमने उत्पाद के पेलोड नहीं गढ़े — REST लिखने वाले एंडपॉइंट पर केवल कॉन्ट्रैक्ट फ़ील्ड (external_ref) वर्णित है; बॉडी का बाकी हिस्सा additionalProperties: true के रूप में खुला रहता है और पाठक को उत्पाद दस्तावेज़ीकरण की ओर भेजा जाता है। अधूरी लेकिन सच्ची परिभाषा, पूरी लेकिन गढ़ी हुई परिभाषा से बेहतर है।
प्रति-ऑपरेशन त्रुटि-कुंजी सूची संपूर्ण नहीं है — x-error-keys केवल उन कुंजियों को सूचीबद्ध करता है जो कमांड के अपने रिकॉर्ड से निश्चित रूप से निकलती हैं, और x-error-keys-exhaustive: false के साथ यह बात कहता है। पूरा शब्दकोश दस्तावेज़ की जड़ (root) में है; जिस कुंजी को आप नहीं पहचानते, उसे सामान्य विफलता मानें। गढ़ी हुई 'पूरी सूची' आपको default शाखा कभी न लिखने की ओर धकेल देती।
खोज टूल परिभाषा में नहीं हैं — search_commands, run_command और list_capabilities केवल चैट लूप के भीतर मौजूद हैं और HTTP पर नहीं बुलाए जा सकते। यदि इन्हें शामिल किया जाता, तो आपका जनरेटर तीन ऐसे मेथड लिख देता जो कभी काम नहीं कर सकते थे।
कोड जनरेशन: परिभाषा से एक टाइप्ड क्लाइंट
आपके पास परिभाषा है; अब उससे काम करने वाला कोड जनरेट करें। `lg codegen` OpenAPI दस्तावेज़ पढ़ता है और एक ही फ़ाइल वाला, बिना निर्भरता का क्लाइंट लिखता है — TypeScript (टाइप घोषणाएँ और एक पतला कॉल रैपर) या PHP (PHPDoc array shapes वाली एक क्लाइंट क्लास)। कोई `npm install` नहीं, कोई composer नहीं: TypeScript की ओर `fetch`, PHP की ओर `ext-curl`।
जनरेशन आपकी मशीन पर होता है, हमारे सर्वर पर नहीं। यह पसंद की बात नहीं है: परिभाषा को एक बार अपनी रिपॉज़िटरी में पिन करें (`lg spec --out=...`) और वही कमांड हर बिल्ड पर बिना नेटवर्क और बिना टोकन के चलती है, इसलिए आपका CI कभी हमारे अपटाइम पर निर्भर नहीं होता। और क्योंकि जनरेट किया गया कोड वह कोड है जो आपके ERP में चलता है, उसे किसी API से खींचने के बजाय अपनी रिपॉज़िटरी में रखने का मतलब है कि हर बदलाव `git diff` में दिखाई देता है।
जनरेट किया गया क्लाइंट Logistivo की तीनों रेल को सही ढंग से संभालता है, और कौन-सी रेल कौन-सी है, यह अनुमान से नहीं बल्कि दस्तावेज़ से सीखता है: हर ऑपरेशन `x-logistivo.surface` में अपनी रेल घोषित करता है। कमांड रेल `{success, data:{…}}` लिफ़ाफ़े को खोलती है; REST सिंक सूची लिफ़ाफ़े में नहीं होती और जैसी है वैसी लौटाई जाती है (उसे खोलने से `next_cursor` गिर जाता); REST लेखन एंडपॉइंट की अपनी उत्पाद बॉडी लौटाता है। सामान्य-उद्देश्य वाला जनरेटर यह अंतर नहीं जानता — हमारा जानता है।
टाइप अनुमान पर आधारित नहीं हैं: हर कमांड का आर्गुमेंट इंटरफ़ेस उसी JSON Schema से जनरेट होता है जिसे सहायक देखता है। अनिवार्य अनिवार्य ही रहता है, enum यूनियन टाइप बन जाते हैं, नेस्टेड ऑब्जेक्ट नेस्टेड टाइप बन जाते हैं। व्यवहार में: यदि सर्वर किसी फ़ील्ड को अनिवार्य मानता है, तो उसे भूलने वाली कॉल प्रोडक्शन में 422 के साथ विफल नहीं होती — वह कंपाइल के समय ही विफल हो जाती है।
फ़ाइल में कोई जनरेशन टाइमस्टैम्प नहीं लिखा जाता: समान फ़्लैग के साथ समान परिभाषा एक जैसे बाइट्स बनाती है। इसलिए दोबारा जनरेट करने से `git diff` में कोई शोर नहीं होता, और जो एक चीज़ वास्तव में बदली — कॉन्ट्रैक्ट — वह दिखाई देती रहती है।
1. परिभाषा पिन करें — परिभाषा आपकी भूमिका के लिए जनरेट होती है; उसमें हर ऑपरेशन उस टोकन से बुलाया जा सकता है। फ़ाइल को कमिट करें। 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` स्कीमा एक इंटरफ़ेस बन जाता है (PHP में एक array shape)। अनिवार्य फ़ील्ड अनिवार्य ही रहते हैं, enum यूनियन बन जाते हैं। TypeScript में किसी अनिवार्य फ़ील्ड को भूलना कंपाइल त्रुटि है; PHP में आपका IDE और PHPStan वही आकार देखते हैं।
त्रुटि क्लास — ट्रांसपोर्ट वर्गीकरण (`error_code`) और व्यावसायिक वर्गीकरण (`error_key`) अलग-अलग फ़ील्ड हैं; पुष्टि गेट और रेट लिमिट अलग-अलग त्रुटि प्रकार हैं। त्रुटि-कुंजी यूनियन अज्ञात मानों के लिए खुला रहता है — जब सर्वर कोई नई कुंजी घोषित करता है, तो आपका कोड कंपाइल होना बंद नहीं करता, वह `default` शाखा में चला जाता है।
एक सही पुनः प्रयास नीति — स्वचालित पुनः प्रयास केवल सुरक्षित कॉल पर लागू होते हैं: पढ़ने वाली कॉल, और ऐसी लिखने वाली कॉल जिनमें आइडेम्पोटेंसी कुंजी हो। बिना कुंजी वाली लिखने वाली कॉल का टाइमआउट होना 'कुछ नहीं लिखा गया' नहीं दर्शाता, इसलिए क्लाइंट उसे कभी आँख मूँदकर नहीं दोहराता। 429 पर यह कोई विलंब गढ़ने के बजाय सर्वर के `Retry-After` तक प्रतीक्षा करता है।
परिणाम बॉडी टाइप्ड नहीं हैं — कमांड के परिणाम `unknown` (PHP में `mixed`) के रूप में लौटते हैं, उसी कारण से जैसे स्वयं परिभाषा में: परिणाम के आकार कमांड का व्यावसायिक आउटपुट हैं, कॉन्ट्रैक्ट का हिस्सा नहीं। अनुमानित परिणाम टाइप पहली बार किसी फ़ील्ड के खिसकते ही झूठ बोलने लगता।
जनरेट की गई फ़ाइल को हाथ से संपादित नहीं किया जाता — यह एक आउटपुट है, स्रोत नहीं। यदि आपको अतिरिक्त व्यवहार चाहिए, तो जनरेट की गई क्लास को रैप करें; उसके भीतर आप जो कुछ भी लिखते हैं, वह अगले जनरेशन पर खो जाता है।
खोज टूल जनरेट नहीं किए जाते — `search_commands`, `run_command` और `list_capabilities` केवल चैट लूप के भीतर रहते हैं और HTTP पर नहीं बुलाए जा सकते; वे परिभाषा में नहीं हैं और इसलिए क्लाइंट में भी नहीं। इन्हें शामिल करने का अर्थ होता तीन ऐसे मेथड लिखना जो कभी काम नहीं करते।
ईमानदार दायरा
हम इस खंड को छोटा करने के बजाय बढ़ाना पसंद करेंगे। किसी इंटीग्रेशन कॉन्ट्रैक्ट का मूल्य इस बात में कम है कि वह क्या वादा करता है, और इसमें अधिक है कि वह कितनी स्पष्टता से बताता है कि वह क्या नहीं करता।
CLI किसी टेनेंट उपयोगकर्ता के संदर्भ में चलता है — हर कमांड उस उपयोगकर्ता की कंपनी और भूमिका के तहत चलती है जिसका टोकन प्रस्तुत किया गया है। प्लेटफ़ॉर्म-ऑपरेटर मोड — कंपनियों के पार पढ़ने वाला प्रशासनिक मोड — इस सतह से बाहर है और यहाँ से नहीं खोला जाएगा।
आपकी कमांड सूची आपकी भूमिका पर निर्भर करती है — एक शिपर खाता 646 कमांड देखता है, एक कैरियर 621, एक कस्टम्स ब्रोकर 392, एक एफ़िलिएट 55। यदि आपके कैटलॉग में कोई कमांड गायब है, तो पहले भूमिका जाँचें; यदि वह सूचीबद्ध है लेकिन अस्वीकार हो रही है, तो कुंजी का स्कोप और एक्सेस स्तर जाँचें। ड्राइवर खातों की इस सतह तक कोई पहुँच नहीं है।
कुछ कमांड क्रेडिट खर्च करती हैं — टैरिफ़ पूछताछ, दस्तावेज़ जनरेशन और कुछ अन्य AI-आधारित कमांड आपके प्लान के क्रेडिट शेष से लेती हैं। हर कैटलॉग पंक्ति credit_cost {mode, credits} रखती है: fixed प्रति कॉल का सटीक शुल्क है, read_only कभी शुल्क नहीं लेता, और computed का अर्थ है कि शुल्क कॉल पर निर्भर करता है — तब credits null होता है और वास्तविक आँकड़ा पुष्टि कार्ड पर दिखाई देता है। प्रीफ़्लाइट (dry_run) बताता है कि एक कॉल कितना शुल्क लेगी और क्या आपका शेष उसे पूरा करता है।
इंटीग्रेशन कुंजियाँ डैशबोर्ड चैट नहीं चला सकतीं — डैशबोर्ड के भीतर का AI सहायक लोगों के लिए है। इंटीग्रेशन कुंजी से सहायक रन शुरू करना या जारी रखना 403 के साथ अस्वीकार कर दिया जाता है; एजेंट कमांड एंडपॉइंट, lg या MCP चैनल का उपयोग करते हैं, जहाँ हर कमांड कुंजी के एक्सेस स्तर पर चलती है और उसके लेखन इंटीग्रेशन लेखन के रूप में दर्ज होते हैं।
कैटलॉग मौजूदा REST API की जगह नहीं लेता — Logistivo वेब और मोबाइल ऐप को चलाने वाली REST सतह अपनी जगह पर रहती है और पिछली संगतता (backwards-compatibility) के नियम के अधीन बनी रहती है। कमांड कैटलॉग संसाधन CRUD की जगह नहीं लेता; यह क्रियाओं (verbs) की परत है — किसी काम को करने का एकमात्र, ऑडिट किया गया तरीका।
सूची कमांड आज छोटी विंडो लौटाती हैं — जब तक कोई सूची कमांड अपने स्कीमा में cursor और updated_since घोषित नहीं करती, उसकी अधिकतम सीमा 20 पंक्तियाँ है और कोई कर्सर नहीं होता। इसे आपके डेटा की पूरी प्रति निकालने के लिए डिज़ाइन नहीं किया गया है; इंक्रीमेंटल सिंक कमांड-दर-कमांड लागू हो रहा है।
अक्सर पूछे जाने वाले प्रश्न
Logistivo CLI का उपयोग किस लिए होता है?
यह आपके Logistivo खाते का काम टर्मिनल, स्क्रिप्ट या आपके अपने AI एजेंट से चलाता है: लोड और ट्रिप, डिमांड, बोलियाँ और टेंडर, फ़्लीट, ड्राइवर और उनके खर्च, दस्तावेज़, संपर्क और चालू खाते, इनवॉइस और लेखांकन, गोदाम और स्टॉक, टीम सदस्य, HS टैरिफ़ और एंटी-डंपिंग शुल्क। पैनल की हर लिखने वाली कार्रवाई के लिए एक कमांड है; भुगतान, कानूनी सहमति और खाता बंद करना जानबूझकर ब्राउज़र में ही रहते हैं। यही कमांड ERP/CRM इंटीग्रेशन के लिए HTTP पर और MCP चैनल के ज़रिए भी बुलाई जा सकती हैं।
Logistivo CLI में कमांड के नाम कैसे रखे जाते हैं?
आकार है: lg --parameter=value — डोमेन एक बहुवचन इकाई है (loads, demands, invoices, export-documents) और क्रिया एक बंद शब्दावली से आती है जो केवल सोच-समझकर लिए गए निर्णय से बढ़ती है (list, get, create, update, search, set-status, generate आदि)। एक इकाई की हर क्रिया एक ही डोमेन में रहती है, और (domain, verb) जोड़ी पूरे कैटलॉग में अद्वितीय है।
मैं CLI में प्रमाणीकरण कैसे करूँ?
इंटरैक्टिव रूप से, lg login एक अनुमोदन कोड दिखाता है, जिसकी पुष्टि आप Logistivo में साइन इन करने के बाद अपने ब्राउज़र में करते हैं — टर्मिनल में कोई पासवर्ड या कुंजी टाइप नहीं की जाती, और सत्र तब तक साइन इन रहता है और स्वयं को नवीनीकृत करता रहता है जब तक आप lg logout नहीं चलाते। lg login --password (ईमेल और पासवर्ड) एक वैकल्पिक (fallback) तरीके के रूप में उपलब्ध रहता है। सर्वर पर और CI में, पैनल में या lg keys create से जारी इंटीग्रेशन कुंजी का उपयोग करें: lg login --api-key उसे एक स्थानीय प्रोफ़ाइल में सहेजता है, या उसे LOGISTIVO_TOKEN एनवायरनमेंट वेरिएबल में रखें। HTTP पर टोकन Authorization: Bearer हेडर में जाता है।
क्या मैं अपने ERP इंटीग्रेशन के लिए एक सर्विस खाता बना सकता हूँ?
नहीं। इंटीग्रेशन पैनल में बनाए गए किसी वास्तविक कंपनी उपयोगकर्ता के टोकन से जुड़ता है। बिना कंपनी वाली कृत्रिम पहचान मल्टी-टेनेंट अलगाव को निष्क्रिय कर देती है, ऑडिट लेजर में "इसे किसने चलाया" कॉलम को निरर्थक बना देती है, और एक ऐसा ब्रिज छोड़ जाती है जो उसके मालिक के जाने पर भी चुप नहीं होता। सही तरीका है एक समर्पित उपयोगकर्ता, जिसकी भूमिका सीमित हो और जिसका एक नामित मालिक हो।
क्या Logistivo में परीक्षण (सैंडबॉक्स) वातावरण है?
हाँ, और यह स्वयं-सेवा है: आपकी कंपनी के लिए एक अलग सैंडबॉक्स टेनेंट खोला जाता है — वही कोड, वही कमांड कैटलॉग, उसका अपना क्रेडिट लेजर। वातावरण कुंजी की कंपनी से निकाला जाता है और अनुरोध के साथ नहीं भेजा जा सकता; गलत प्रोफ़ाइल से की गई कॉल सर्वर की ओर 403 ENVIRONMENT_MISMATCH के साथ रुक जाती है। सैंडबॉक्स में खोली गई डिमांड कभी वास्तविक कैरियरों तक नहीं पहुँचती, सैंडबॉक्स इवेंट कभी आपके लाइव वेबहुक सब्सक्रिप्शन पर डिलीवर नहीं होता, और आपका लाइव शेष नहीं बदलता। एंडपॉइंट: POST /api/common/integration-sandbox (खोलना), POST /api/common/integration-sandbox/keys (कुंजी), GET /api/common/integration-sandbox/go-live (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, CLI एग्ज़िट कोड 4)। कमांड को --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 की जगह नहीं लेता; यह क्रियाओं की परत है — कोई कार्रवाई करने का एकमात्र, भूमिका-गेट वाला, पुष्टि-गेट वाला और ऑडिट किया गया तरीका।
मुझे Logistivo API कुंजी कैसे मिलती है और वह क्या कर सकती है?
टीम-प्रबंधन अनुमति वाला कोई मैनेजर इसे पैनल में Settings › Integration keys के अंतर्गत, या टर्मिनल से lg keys create से जारी करता है। कुंजी किसी वास्तविक टीम सदस्य की ओर से काम करती है और उसकी तीन स्वतंत्र सेटिंग्स हैं: स्कोप (read कैटलॉग और न लिखने वाली कमांड खोलता है, write हर कमांड खोलता है — पुष्टि गेट जैसा है वैसा रहता है), वैकल्पिक डोमेन अनुमतियाँ, और एक एक्सेस स्तर — रोज़मर्रा के संचालन के लिए employee (डिफ़ॉल्ट), या टीम, सेटिंग्स, कुंजियों और पैसे के लिए manager। यह केवल एक बार दिखाई जाती है और सर्वर पर संग्रहीत नहीं की जाती; इसे रोटेट, ट्रांसफ़र और रद्द किया जा सकता है। जिस सदस्य की ओर से यह काम करती है, उसके जाने पर कुंजी भी बंद हो जाती है। कोई सर्विस खाता नहीं है।
यदि मैं किसी आइडेम्पोटेंसी कुंजी को किसी दूसरी कमांड के लिए दोबारा उपयोग करूँ तो क्या होगा?
सर्वर 409 idempotency_conflict उत्तर देता है और उस कमांड का नाम बताता है जिसके लिए कुंजी पहली बार उपयोग हुई थी; कुछ नहीं चलता और कुछ भी दोहराया नहीं जाता। कुंजियाँ आपकी कंपनी तक सीमित हैं, एक कमांड से बँधी हैं और 24 घंटे के लिए लॉक रहती हैं — उसके बाद वही कुंजी एक नया निष्पादन शुरू करती है।
मेरे इंटीग्रेशन पर रेट लिमिट कैसे लागू होती हैं?
प्रति टोकन, प्रति मिनट, तीन बकेट में: कैटलॉग पढ़ना 120, पढ़ने वाली कमांड 120, लिखने वाली कमांड 30। 429 हमेशा Retry-After और retry_after, limit तथा bucket वाली बॉडी रखता है; उतनी देर प्रतीक्षा करें और पुनः प्रयास करें। कैटलॉग वर्तमान संख्याएँ rate_limits के अंतर्गत प्रकाशित करता है।
व्यावसायिक अस्वीकृति और ट्रांसपोर्ट त्रुटि में अंतर कैसे करूँ?
पहले error_code पर शाखा बनाएँ: failed (422) व्यावसायिक अस्वीकृति है और INSUFFICIENT_CREDITS या NOT_FOUND जैसी स्थिर error_key रखती है; server_error (5xx) और नेटवर्क त्रुटियों का पुनः प्रयास उसी आइडेम्पोटेंसी कुंजी के साथ किया जाता है; rate_limited (429) पर प्रतीक्षा की जाती है। त्रुटि के पाठ पर कभी शाखा न बनाएँ।
क्या Logistivo वेबहुक भेजता है? किन इवेंट के लिए?
हाँ। आप एक https पता पंजीकृत करते हैं और अपनी ज़रूरत के इवेंट चुनते हैं; उनके होते ही एक हस्ताक्षरित POST पहुँचता है। आज 13 इवेंट सब्सक्राइब किए जा सकते हैं: लोड बनाया गया/स्थिति बदली/ड्राइवर असाइन हुआ, डिमांड बनाई गई और स्थिति बदली, बोली लगाई गई/संशोधित हुई/स्वीकृत हुई, इनवॉइस ड्राफ़्ट/जारी/रद्द, और गोदाम आरक्षण बनाया गया/स्थिति बदली। हर नाम के पीछे एक इवेंट क्लास है जो वास्तव में डिस्पैच होती है — ऐसा कुछ नहीं है जिसकी घोषणा की गई हो और जो फिर कभी फ़ायर न हुआ हो, क्योंकि ऐसा इवेंट एक चुपचाप होने वाली विफलता है जिसकी प्रतीक्षा इंटीग्रेटर हमेशा करता रहता है। सब्सक्रिप्शन Settings › Integration › Webhooks के अंतर्गत, या टर्मिनल से lg webhooks create से बनाए जाते हैं।
Logistivo वेबहुक हस्ताक्षर का सत्यापन कैसे करूँ?
हर अनुरोध एक X-Logistivo-Signature हेडर रखता है: t=,v1=। हस्ताक्षरित स्ट्रिंग "." है, एल्गोरिदम HMAC-SHA256 है और कुंजी सब्सक्रिप्शन सीक्रेट है। चार नियम: (1) कच्चे (RAW) बाइट्स का सत्यापन करें — बॉडी को डिकोड करके फिर से सीरियलाइज़ करना (JSON.stringify / json_encode) उसी डेटा को अलग बाइट्स में बदल देता है और हस्ताक्षर मेल खाना बंद कर देता है; यही सबसे आम गलती है; (2) टाइमस्टैम्प जाँचें और ऐसा कुछ भी छोड़ दें जहाँ |now − t| > 300 s हो, भले ही हस्ताक्षर सही हो; (3) hash_equals / timingSafeEqual से स्थिर समय में तुलना करें; (4) डुप्लिकेट event_id के आधार पर हटाएँ, डिलीवरी id के आधार पर नहीं — replay पर event_id अपरिवर्तित रहता है जबकि डिलीवरी id बदल जाती है। काम करने वाले Node और PHP रिसीवर रिपॉज़िटरी में examples/webhook-receiver/ में हैं और --selftest के साथ स्वयं का परीक्षण करते हैं।
यदि कोई वेबहुक डिलीवर नहीं हो पाता तो क्या होता है? क्या मैं इवेंट खो देता हूँ?
नहीं। यदि आपका रिसीवर 2xx नहीं लौटाता, तो डिलीवरी पुनः प्रयास शेड्यूल में जाती है: 60 · 300 · 1800 · 7200 · 21600 सेकंड, कुल 6 प्रयास, लगभग 8.6 घंटे की विंडो। 410 Gone को छोड़कर हर एक विफलता का पुनः प्रयास होता है, 4xx सहित — किसी व्यावसायिक इवेंट को खोना कुछ अतिरिक्त अनुरोधों से अधिक महँगा है। लगातार 10 डिलीवरी के सभी प्रयास समाप्त होने के बाद सब्सक्रिप्शन म्यूट हो जाता है और कारण दर्ज किया जाता है, ताकि "कुछ भी क्यों नहीं आ रहा" का उत्तर मिल सके। डिलीवरी लेजर हर प्रयास (स्टेटस कोड, अवधि, त्रुटि) रखता है और आप पैनल से या lg webhooks replay से किसी एक डिलीवरी को फिर से भेज सकते हैं। इंक्रीमेंटल सिंक (updated_since + cursor) सुरक्षा जाल के रूप में अब भी मौजूद है।
क्या मेरा AI एजेंट वह सब कर सकता है जो कोई उपयोगकर्ता पैनल में कर सकता है?
लगभग सब कुछ। पैनल की हर लिखने वाली कार्रवाई के लिए एक कमांड है — पैनल के लिखने वाले एंडपॉइंट से मापने पर, दायरे में आने वाले 100% एंडपॉइंट कवर हैं — और यही कमांड lg, HTTP और MCP चैनल के लिए खुली हैं। जानबूझकर रखे गए अपवाद पहचान और पैसे से जुड़े चरण हैं: साइन इन करना, पैकेज खरीदना, 3D Secure के साथ कार्ड जोड़ना, कानूनी पाठों को स्वीकृत करना और खाता बंद करना व्यक्ति के ब्राउज़र में रहते हैं, और lg handoff-links generate उनके लिए लिंक लौटाता है। इंटीग्रेशन कुंजियाँ, वेबहुक और सैंडबॉक्स lg की बिल्ट-इन कमांड से प्रबंधित होते हैं, क्योंकि वे सीक्रेट केवल एक बार लौटाते हैं।
क्या मैं CLI या API से कमांड को PDF या फ़ोटो जैसी फ़ाइलें दे सकता हूँ?
हाँ। lg के साथ, किसी स्थानीय पथ के आगे @ लगाएँ (--attachment_uuid=@./cmr.pdf) और lg पहले फ़ाइल अपलोड करता है; जब किसी कमांड में एक ही फ़ाइल फ़ील्ड हो, तो --file एक शॉर्टकट है, और lg upload केवल अपलोड करता है। HTTP पर, फ़ाइल को multipart के रूप में POST /api/common/commands:upload पर भेजें और लौटाया गया attachment_uuid कमांड को पास करें; MCP क्लाइंट upload_attachment टूल का उपयोग करते हैं। प्रकार सामग्री से पहचाना जाता है, अपलोड उपयोगकर्ता के होते हैं और 24 घंटे तक उपयोग योग्य रहते हैं, और उसी फ़ाइल को दोबारा अपलोड करने पर वही id लौटती है।
employee और manager इंटीग्रेशन कुंजी में क्या अंतर है?
एक्सेस स्तर तय करता है कि कोई कुंजी कितना भारी काम कर सकती है। employee कुंजी, जो नई कुंजियों का डिफ़ॉल्ट है, रोज़मर्रा का संचालन चलाती है: लोड, डिमांड, बोलियाँ, ट्रिप, फ़्लीट, दस्तावेज़ और संपर्क। manager कुंजी प्रबंधन का काम भी कर सकती है — टीम सदस्य और भूमिकाएँ, कंपनी सेटिंग्स, इंटीग्रेशन कुंजियाँ, बैंक खाते, सहेजे गए कार्ड, एफ़िलिएट भुगतान। कोई कुंजी कभी भी उस व्यक्ति से अधिक अधिकार नहीं रखती जिसकी ओर से वह काम करती है, और manager कमांड बुलाने वाली employee कुंजी को INSUFFICIENT_KEY_LEVEL मिलता है। स्तर पैनल में या lg keys update --access-level=manager से बदलें।
क्या कोई एफ़िलिएट (रेफ़रल पार्टनर) CLI का उपयोग कर सकता है?
हाँ। एफ़िलिएट खाते को अपना अलग कैटलॉग मिलता है — रेफ़रल, लीड, CRM नोट और कार्य, सेल्स डेक, कमाई और भुगतान के लिए 55 कमांड — और वह इसे किसी भी अन्य भूमिका की तरह 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.