Logistivo CLI: lojistik operasyonunuzu terminalden ve ERP'nizden çalıştırın
Tek bir komut kataloğu üç yüzeyi birden besliyor: lg terminal istemcisi, paneldeki yapay zekâ sohbeti ve dış AI asistanlarının bağlandığı kanal. Bir yetenek bir kez yazılıyor, üçünde birden beliriyor — ve paneldeki her yazma işleminin artık bir komutu var; ekibinizin ekranda yaptığı işi betikleriniz ve kendi yapay zekâ ajanlarınız da yapabilir. Ödeme, hukuki onay ve hesap kapatma bilinçli olarak tarayıcıda kalır. Bu sayfa bir sözleşmedir. Aşağıdaki komut tablosu elle yazılmadı; her istekte canlı komut defterinden üretiliyor.
Logistivo CLI nedir?
Logistivo CLI (lg), hesabınızdaki işleri — yük ve sefer, talep, teklif ve ihale, filo ve sürücü, evrak, cari ve iletişim, fatura ve muhasebe, depo ve stok, ekip üyeleri ve gümrük tarifesi — terminalden, bir betikten ya da kendi yapay zekâ ajanınızdan çalıştıran komut satırı istemcisidir. Komutlar istemcinin içine gömülü değildir: istemci komut kataloğunu sunucudan çeker ve kendini ona göre çizer. Aynı komutlar istemci kurmadan HTTP ile de çağrılabilir — ERP ve CRM entegrasyonları bu yolu kullanır — ve dış yapay zekâ asistanlarının bağlandığı MCP kanalından da.
Komut biçimi tek: lg --parametre=değer. Katalogda bugün 175 alana yayılmış 721 komut var; tek bir rolün gördüğü en geniş liste 646 komut ve 165 alan.
Paneldeki her yazma işleminin bir komutu var — panelin yazma uçlarıyla karşılaştırılarak ölçüldü, kapsamdakilerin %100'ü karşılanıyor. Ödeme (3D Secure), hukuki onay ve hesap kapatma bilinçli olarak tarayıcıda kalır; bunlar için komut size bir bağlantı döndürür.
Evrak ya da fotoğraf alan komutlar tarayıcı dışında da çalışır: --attachment_uuid=@./cmr.pdf yazın, lg dosyayı önce yükler; HTTP'de /api/common/commands:upload ucuna yükleyip dönen attachment_uuid'yi komuta verirsiniz.
Entegrasyon anahtarlarının bir yetki düzeyi vardır: günlük operasyon için çalışan (employee — yeni anahtarın varsayılanı), ekip, ayarlar, anahtarlar ve para işleri için yönetici (manager). Bir anahtar, adına çalıştığı kişiden fazla yetki taşımaz.
Bayraklar uydurulmaz: her bayrak komutun JSON Schema'sındaki parametre adıdır; tip ve zorunluluk da oradan gelir.
Yazan komutlar onay ister; geri alınamaz olanlar onaysız hiç çalışmaz (HTTP'de 409, CLI'da çıkış kodu 4).
Tekrar denemek çift kayıt üretmez: idempotency_key verilen bir çağrı en fazla bir kez koşar.
Her yürütme tek bir denetim defterine yazılır — komutun terminalden mi, sohbetten mi, bir asistandan mı geldiği kayıtlıdır.
Bugün ne canlı, ne yolda
Bu bölüm bilinçli olarak sayfanın başında duruyor. Bir entegrasyon dokümanının en pahalı hatası, henüz açılmamış bir ucu açılmış gibi anlatmaktır: entegratör kodu yazar, uç 404 döner ve güven bir daha geri gelmez.
Sözleşme donduğu için bugün yazdığınız entegrasyon kodu kalan parçalar açıldıkça çalışmaya devam eder. Bilmediğiniz alanı yok saymak zorundasınız; kırmadan ekleyebilmemizin kuralı budur.
Komut kataloğu ve kimlik tablosu — Tüm komutların kamuya açık alan/fiil kimliği dondurulmuştur; sözleşme sürümü her katalog yanıtında ve X-Contract-Version başlığında 1 olarak yayınlanır. Bu sayfadaki tablo canlı kayıt defterinden üretilir: sunucuya eklenen komut kendiliğinden belirir, kaldırılan kaybolur.
Kimliksiz keşif ucu — GET /api/public/cli/catalog — komut adları, alan/fiil kimliği, açıklama, JSON Schema parametreleri, kapı bayrakları ve sürümleme alanları (since, deprecated_at, replaced_by, aliases). Kimlik istemez: jeton üretmek entegrasyon kararından SONRA gelen adımdır. Yanıtta tek satır kiracı verisi yoktur.
Kimlikli katalog ve yürütme uçları — GET /api/common/commands, GET /api/common/commands/{name} ve POST /api/common/commands/{name}. Rol kapısı, onay kapısı, idempotency ve denetim defteri; sohbetin ve terminalin de geçtiği tek zorlama noktasında yaşar.
Panel kapsaması: her yazma işleminin bir komutu var — 175 alana yayılmış 721 komut, panelin yazma uçlarıyla karşılaştırıldı: kapsamdaki her ucun arkasında bir komut var (ucun aynası ya da aynı ortak servis), kanıtsız uç yok. Bilinçli olarak kapsam dışı: tarayıcıda kalan 3D Secure ödeme, hukuki onay, hesap kapatma ve oturum açma; lg'nin yerleşik komutları olan anahtar, webhook ve kum havuzu yönetimi; ve sürücü uygulamasının kendi uçları.
Ön uçuş (dry_run): çalıştırmadan görmek — İstek gövdesine dry_run: true koyulduğunda komut çalışmaz: doğrulama, rol/kapsam kapısı, hedef çözümü ve kredi hesabı koşar, önizleme döner; hiçbir yazma olmaz, kredi düşmez ve idempotency anahtarı tüketilmez. Toplu uçta da var, parti başına. Ön uçuş komutun işleyicisine hiç girmez; yayına alındığında o günkü katalogdaki yazan komutların tamamında koşan 178 ön uçuşta tek bir yazan SQL ifadesi çıkmadı.
Entegrasyon anahtarları — Gerçek bir ekip üyesi adına çalışan, panelden ya da lg keys create ile üretilen API anahtarları: okuma/yazma kapsamı, yetki düzeyi (varsayılan çalışan, ya da yönetici), süre, son kullanım, yenileme, devir ve iptal. lg login --api-key, lg whoami ve sunucuda da iptal eden lg logout bunun üstünde durur.
Kum havuzu — canlıya dokunmadan yazma provası — Firma başına ayrı bir kum havuzu kiracısı, aynı komut kataloğuyla; self-servis açılır ve kendi anahtarını üretir. Kredi, pazar yeri ve webhook yönlendirmesi iki ortam arasında bölünmüştür; ortam anahtarın firmasından türetilir, istekle verilemez.
Sürümleme, hata taksonomisi, idempotency ve hız sınırı — Komutlar since / deprecated_at / replaced_by / aliases taşır; kullanımdan kalkan komut X-Deprecated başlığıyla cevap verir. İş hataları taşıma katmanı error_code'unun yanında kararlı bir error_key taşır ve anahtar sözlüğü katalogda yayınlanır. Idempotency anahtarları firmanıza özeldir, tek komuta bağlıdır ve 24 saat kilitli kalır. Hız sınırı jeton başınadır, üç kovadadır ve her 429 Retry-After taşır.
Giden webhook: olay olduğunda POST — 13 olay için imzalı push canlı. Abonelik panelden ya da lg webhooks ile yönetilir; imza zaman damgasını kendi içinde taşır, tekrar takvimi 60 · 300 · 1800 · 7200 · 21600 saniyedir ve susturma sebebi daima yazılır. Her olay adının arkasında gerçekten yayılan bir olay sınıfı vardır — ilan edilip hiç gelmeyen olay yoktur. Çekme rayı (updated_since + imleç) kaldırılmadı: webhook onun yerine değil yanına kondu.
Dosya alan komutlar — 38 komut bir evrak ya da fotoğraf alır — CMR, fatura, araç ruhsatı, palet fotoğrafları. Dosyayı bir kez POST /api/common/commands:upload ucuna yükleyin ya da --attachment_uuid=@./dosya.pdf ile lg'ye yaptırın, dönen attachment_uuid'yi komuta verin; MCP istemcileri upload_attachment aracını kullanır. Dosya türü içerikten tespit edilir ve yükleme 24 saat kullanılabilir kalır.
lg terminal istemcisi — npm'de MIT lisansıyla yayında: `npm install -g @lgstv/lg` ile kurun ya da kurmadan `npx @lgstv/lg` ile çalıştırın. Tek dosyalık ve bağımlılıksızdır; HTTP yüzeyi açık olduğu için onu kullanmadan da entegre olabilirsiniz. Tarayıcıda onayladığınız bir kodla oturum açar ve oturumu kendiliğinden yenileyerek açık tutar; yerel dosyaları sizin yerinize yükler (@yol, --file, lg upload), entegrasyon anahtarlarını yönetir (lg keys), sırrı asla komut satırından almaz, Retry-After'a uyar, 5xx'te aynı idempotency anahtarıyla tekrar dener, kullanımdan kalkan komutta ve daha yeni sözleşme sürümünde uyarır.
Artımlı senkron: imleçli sayfalama ve updated_since — Aşağıdaki sözleşme (limit + opak imzalı imleç, next_cursor, updated_since) sabittir ve liste komutlarına yayılmaktadır. Bir liste komutu JSON Schema'sında cursor ve updated_since ilan edene kadar onu küçük bir pencere sayın: tavan 20 satır, imleç yok.
Farkımız: istemci komut bilmez, kataloğu çizer
Bu, sayfanın geri kalanını anlamlı kılan tek karar. Sıradan bir CLI'da komutlar istemcinin içine yazılır; Logistivo'da sunucuda durur.
Klasik kurguda sunucu yeni bir yetenek kazandığında istemcinin de yeni bir sürümü çıkmalı, kullanıcı da onu kurmalıdır. Arada geçen sürede iki taraf farklı şeyler bilir ve bu, entegrasyonların en sessiz kırılma noktasıdır: betik çalışır, çıkış kodu 0 döner, ama komut sunucudaki gerçeği anlatmaz.
Logistivo'da bir komutun tanımı tek bir kayıttır: adı, ne yaptığı, JSON Schema parametreleri, hangi rollerin görebildiği, onay gerektirip gerektirmediği ve geri alınabilir olup olmadığı. lg açıldığında bu kataloğu çeker; yardım metnini, bayrakları ve girdi doğrulamasını ondan üretir. Sunucuya bir komut eklendiği an istemciyi güncellemeden lg onu tanır.
Aynı katalog paneldeki yapay zekâ sohbetini ve dış AI asistanlarının bağlandığı kanalı da besler. Bir yetenek bir kez yazılır, üç yüzeyde birden belirir — ve üçü de aynı rol kapısından, aynı onay kapısından ve aynı denetim defterinden geçer. Ayrı bir CLI komut envanteri yoktur; olsaydı üç yüzey altı ay içinde sessizce ayrışırdı.
Sürüm sürüklenmesi yok — İstemcinin bildiği komut listesi tanım gereği sunucununkiyle aynıdır. "Hangi lg sürümünde bu komut var?" diye bir soru yoktur.
Bayrak adı tahmin edilmez — Bir komutun bayrakları, JSON Schema'sındaki parametre adlarının birebir aynısıdır. Bir komutun ne kabul ettiğini öğrenmenin yolu dokümanı okumak değil, kataloğu okumaktır — ve katalog daima günceldir.
CLI'nız hesabınız kadar büyük — Katalog rol filtrelidir: rolünüzün göremediği komut listenizde hiç görünmez. Nakliyeci hesabı 621 komut, yük sahibi 646, gümrük müşaviri 392 komut görür; satış ortağı hesabının ise kendine ait 55 komutluk bir seti vardır.
Doküman geri kalmaz — Bu sayfadaki komut tablosu da aynı defterden üretiliyor. Sözleşme metni ile gerçek davranış arasında elle senkronlanan hiçbir liste yok.
Adlandırma kuralı — komut adları nasıl büyür
Katalog büyüyecek. Yeni komutlar rastgele adlandırılmıyor; altı kural uygulanıyor. Bunları burada yayımlıyoruz çünkü entegrasyonunuzun ömrü boyunca yazacağı adlar bunlar ve tahmin edilebilir olmaları sizin işinize yarıyor.
Alan adı çoğul varlıktır — loads, demands, invoices, export-documents. İki kelimeliler kısa çizgiyle yazılır. Tek istisna sayılamayan isimdir: stock çoğullanmaz, çünkü "stocks" başka bir şeydir.
Bir varlığın bütün fiilleri tek alanda toplanır — loads altında bir yüke dokunan bütün fiiller durur: create, list, get, update, set-status, assign-driver, list-problems, archive ve dahası. Fiil başına yeni alan açmak (load-statuses, load-drivers) aynı varlığı üç ayrı yerde aratır.
Fiil alana sızmaz; alan, DEĞİŞEN varlıktır — Sürücü atamak yükü değiştirir, sürücüyü değil → lg loads assign-driver. Fiilin dolaylı nesnesi (-driver) fiile eklenir, alana değil.
Alt kaynağın kendi alanı olmaz — Fatura kalemi ve evrak kalemi tek başına listelenemez; sahibi üzerinden adreslenir → lg invoices add-line, lg export-documents add-item. Ölçüt tek: bağımsız list/get edemiyorsanız o bir alan değildir.
Daraltma bayraktır, yeni fiil değil — lg fleet-documents list --days=30 doğrudur; "list-expiring" diye ayrı bir fiil yoktur, çünkü pencere zaten bir parametredir. Nitelikli fiil yalnız dönen satır tipi alanın varlığı değilse kullanılır: loads list-problems yük değil, sorun kaydı döndürür.
(alan, fiil) çifti katalog genelinde benzersizdir — Rolleri hiç kesişmeyen iki komut için bile. Aynı çift iki komuta verilseydi entegrasyon kodunuz tek bir ada bakarken CLI, kimin çalıştırdığına göre farklı bir şey koşardı.
Kapsam: paneldeki her iş, bir komutla
Birçok ekip Logistivo'yu kendi yapay zekâ ajanına ya da otomasyon düzeneğine bağlıyor ve bir ajan ancak işi bitirebiliyorsa işe yarar. Kural bu yüzden basit: bir ofis kullanıcısının panelde değiştirebildiği her şeyi bir komut da değiştirebilir — aynı rol kapısının, aynı onay kapısının ve aynı denetim defterinin arkasından.
Bu bir iddia değil, ölçüm. Panelin arkasındaki her yazma ucu komut defteriyle karşılaştırılır; bir uç ancak bir komut onu HTTP aynası olarak beyan ediyorsa ya da aynı ortak servisi çağırıyorsa karşılanmış sayılır. Kapsamdaki yazma uçlarının %100'ü karşılanıyor, kanıtsız uç yok. Dışarıda bırakılan her ucun yazılı bir gerekçesi var — kimlik ve ödeme adımları, entegrasyon kontrol düzlemi, sürücü uygulamasının kendi uçları, istemci telemetrisi, çağıranı olmayan ölü kopyalar — ve bir entegratörü ilgilendirenler aşağıda sayılıyor.
Dosya alan komutlar da aynı kurala tabidir: tablodaki 38 komut bir evrak ya da fotoğraf alır ve hepsi lg'den, HTTP'den ve MCP'den çalışır (bkz. Dosya alan komutlar).
Yönetim işleri de kapsamda, ama daha güçlü bir anahtarın arkasında: tablodaki 87 komut — ekip üyeleri ve roller, firma ayarları, banka hesapları, kayıtlı kartlar, entegrasyon anahtarları — yönetici düzeyli bir entegrasyon anahtarı ister. Varsayılan olan çalışan düzeyli anahtar günlük operasyonu yürütür; bu komutlarda INSUFFICIENT_KEY_LEVEL ile reddedilir.
Satış ortağı hesaplarının kendine ait bir kataloğu vardır: 20 alana yayılmış 55 komut — davetler, adaylar, CRM notları ve görevleri, satış sunumları, kazanç ve ödemeler, artı her rolün sahip olduğu hesap ve ekip komutları. Yalnız satış ortağına ait komutlar aşağıdaki kamuya açık tabloda yer almaz — tablo üç panel rolünü listeler; satış ortağı hesabı onları GET /api/common/commands yanıtında ve lg commands çıktısında görür. Hem satış ortağı hem yük sahibi, nakliyeci ya da gümrük müşaviri olan bir firma iki seti birlikte görür.
Bir ajan işe lg users get ile (API adı get_current_user) başlamalıdır: rolü, kullanılan anahtarın yetki düzeyini, etkin izinleri ve bekleyen bir hukuki onayın ya da doğrulanmamış bir telefon numarasının şu an yazmaları engelleyip engellemediğini döndürür — ajan reddi toplamak yerine önceden kestirebilsin diye.
Kapsam, komut defterini panelin yazma uçlarıyla karşılaştıran bir raporla ölçülür; komutu olmadan panele eklenen bir uç o raporda kanıtsız olarak görünür. Bir komutla ulaşamadığınız bir panel işlemi bulursanız destek ekibine bildirin.
1. Bağlantıyı isteyin — Kişinin kendi tarayıcı oturumunda yapılması gereken iş bir komut değildir, ama komut yüzeyi onu bilir. lg handoff-links generate (API adı get_browser_handoff_link) rolünüzün izin verdiği amaçlar için bir logistivo.com bağlantısı döndürür: package_purchase, payment_cards, legal_documents, integration_keys, affiliate_demo_accounts ve account_close. Ücretsizdir, hiçbir şey yazmaz ve bağlantı sır taşımaz — kişi her zamanki gibi oturum açar.
2. Kişiye verin — Bağlantıyı kullanıcıya gösterin ya da kendi kanalınızdan gönderin. Adımı orada tamamlar: paket için sözleşme onayı ve 3D Secure ödeme, kart ekleme, bekleyen hukuki metinlerin onayı, sırrı bir kez gösterilen bir API anahtarı üretme ya da kendi hesabını kapatma.
3. Sonucu komutla okuyun — Adım tamamlanınca sonucu yeniden komutlara görünür: paket ve kredi bakiyesi, kayıtlı kart (maskeli, yalnız son dört hane), anahtar listesindeki yeni anahtar. Bir ajan sohbette asla kart numarası, ödeme ya da onay almaz.
Ödeme ve 3D Secure — Paket satın almak ya da yükseltmek ve kart eklemek tarayıcıda 3D Secure ister. Komutlar paketleri ve fiyatları listeler, bakiyeyi ve hareketlerini okur, kayıtlı kartları (maskeli) listeler, varsayılan kartı belirler ve kart siler; satın almanın kendisi devir bağlantısından geçer.
Hukuki onay — Hukuki metinleri kişi kendisi, tarayıcıda onaylar. lg users get bekleyen bir onay olduğunu söyler; hiçbir komut onayı veremez.
Hesap kapatma, oturum açma ve parola — Kendi hesabınızı kapatmak, oturum açmak ve parola değiştirmek kimlik adımlarıdır ve tarayıcıda kalır. lg user-accounts preview hesabı kapatmanın ne anlama geldiğini, kapatmadan gösterir.
Entegrasyon anahtarları, webhook ve kum havuzu — Bunları yönetmek yalnız bir kez ve yalnız terminalinizde gösterilmesi gereken sırlar döndürür; bu yüzden katalog komutu değil, kendi HTTP uçları üstünde lg'nin yerleşik komutlarıdır (lg keys, lg webhooks, lg sandbox). Katalogda yalnız sır döndürmeyen iki anahtar komutu vardır: integration-keys list ve integration-keys revoke.
Paneldeki asistan sohbeti — Entegrasyon anahtarları paneldeki yapay zekâ asistanı sohbetini süremez; bir anahtarla koşu başlatmak ya da sürdürmek 403 döner. Ajan bunun yerine komut uçlarından, lg'den ya da MCP kanalından bağlanır — orada her komut anahtarın yetki düzeyiyle koşar ve yazmaları entegrasyon yazması olarak kaydedilir.
Sürücü uygulaması — Sürücü hesaplarının komut kataloğu yoktur; sürücü uygulaması kendi uçlarını kullanır. Ofis kullanıcıları sürücüleri, belgelerini, masraflarını ve seferlerini komutlarla yönetir.
Kurulum ve kimlik
lg, sıfır bağımlılıklı tek dosyalık bir Node betiğidir (Node 18+) ve npm'de @lgstv/lg adıyla yayındadır. Paket iki eş komut kurar: lg ve logistivo — makinenizde lg başka bir kısayola bağlıysa logistivo'yu kullanın. Tek dosya olduğu için bir müşterinin ERP sunucusuna lg.mjs dosyasını kopyalamak da yeter. ERP/CRM entegrasyonu için istemci şart değil — aynı komutlar HTTP ile çağrılıyor.
1. Kurun — Node 18 veya üstü yeterli; başka bağımlılık yok. Global kurun ya da kurmadan npx ile çalıştırın.
2. Onay koduyla oturum açın — lg login kısa bir onay kodu gösterir ve tarayıcınızda logistivo.com/connect adresini açar; SSH'ta, CI'da ya da --no-browser ile yalnız adresi yazar — o adresi telefonunuz dahil herhangi bir cihazda açabilirsiniz. Orada her zamanki gibi oturum açın, sayfadaki kodun terminalinizdekiyle aynı olduğunu kontrol edin, "yalnız okusun" ya da "okusun ve işlem yapsın" erişimini seçip onaylayın. Terminale gizli hiçbir şey yazılmaz: parola, anahtar ya da tek kullanımlık kod yok. Oturum o bilgisayarda açık kalır — terminali kapatmak çıkış yapmaz, lg erişim jetonunu süresi dolmadan kendiliğinden yeniler. lg logout oturumu sunucuda da kapatır; panelde Ayarlar › Entegrasyon anahtarları › AI ve CLI bağlantıları altından da kaldırabilirsiniz. lg login --password (e-posta ve parola) yedek yol olarak durur. lg 0.11 ve sonrası gerekir.
3. Sunucu ve CI için: onay kodu değil anahtar — Bir sunucuda ya da CI işinde kodu tarayıcıda onaylayacak kimse yoktur. Panelden (Ayarlar › Entegrasyon anahtarları) ya da lg keys create ile bir anahtar üretin — isterseniz köprüye adanmış, dar rollü bir ekip üyesi adına — ve LOGISTIVO_TOKEN ortam değişkenine koyun ya da lg login --api-key ile kaydedin. Değişken doluyken yapılandırma dosyası hiç okunmaz. Ayrıntı: "API anahtarı ile bağlanma" bölümü.
4. Kataloğu doğrulayın ve keşfedin — lg commands rolünüzün gördüğü her komutu alanlara göre gruplayıp listeler; lg help o alanın fiillerini, lg help ise tek komutun bütün parametrelerini tipleriyle ve zorunluluk bilgisiyle basar. Bu metinlerin hiçbiri istemcinin içinde yazılı değildir; hepsi katalogdan gelir. Listenin rolünüze göre değiştiğini unutmayın: aynı alanın fiilleri nakliyecide ve müşteride aynı değildir (örneğin loads set-status yalnız nakliyeci kataloğundadır). Bir fiili göremiyorsanız önce rolünüze bakın.
Anahtarı sürüm kontrolüne, CI günlüğüne veya bir sohbet penceresine yazmayın. Onay koduyla ya da entegrasyon anahtarıyla girildiyse lg logout oturumu sunucuda da kapatır; parola oturumunda (lg login --password) yalnız YEREL kopyayı siler ve bunu açıkça söyler. Denetim defteri argümanlarınızı saklar ama anahtarında token, password, IBAN, kart veya OTP geçen alanları ve bir komutun gizli ilan ettiği her parametreyi *** olarak maskeler.
LOGISTIVO_TOKEN — Kişisel erişim jetonu. Doluyken yapılandırma dosyası hiç okunmaz — CI ve sunucu ortamlarında tercih edilen yol budur.
LOGISTIVO_BASE_URL — Sunucu kökü. Varsayılan https://logistivo.com. Yalnız kendi ortamınıza yönlendirme yapıyorsanız değiştirin; --base-url bayrağı da aynı işi tek komut için yapar.
LOGISTIVO_HOME — Yapılandırma ve katalog önbelleğinin dizini. Varsayılan ~/.logistivo. Aynı makinede iki farklı hesapla çalışıyorsanız bunu ayırın.
LOGISTIVO_PROFILE — Hangi profille koşulacağı. `lg profile use` kalıcı seçimdir; bu değişken tek koşu içindir ve CI'da canlı ile kum havuzu profili arasında geçiş yapmanın en kısa yoludur. Olmayan bir profil adı sessizce yok sayılmaz, hata verir.
NO_COLOR — Dolu olduğunda ANSI renk kodu basılmaz (`--no-color` bayrağının kalıcı hâli). Günlük dosyasına ya da CI çıktısına yazan bir köprüde bunu açın; renk kaçış dizileri, günlüğü sonradan okuyan araçları bozar.
İstemci ergonomisi
Aşağıdakiler `lg` istemcisinin gündelik kullanımını kolaylaştıran yeteneklerdir. Hiçbiri HTTP sözleşmesini değiştirmez — doğrudan HTTP ile bağlanıyorsanız bu bölümü atlayabilirsiniz.
Birden çok ortam ve anahtar — Prova ile canlıyı ya da müşteri ve nakliyeci köprülerini ayrı profillerde tutun. Profil listesi jetonu hiçbir zaman basmaz; her satır jetonun sha256 parmak izini gösterir. Komut kataloğu profil, adres ve jeton başına ayrı önbelleklenir, bu yüzden iki rol birbirinin komut listesini göremez.
Artımlı senkron: lg sync — Kılavuzdaki senkron döngüsünü tek komutta koşar: varlık başına su seviyesi, updated_since ile imleç, JSONL çıktı ve beş dakikalık emniyet payı. İlk dolum için --full kullanılır. Komut yalnız okur; --write diye bir bayrağı yoktur. lg sync --list rolünüzün senkronlanabilir varlıklarını katalogdan üretir.
Hata deneyimi ve kabuk tamamlaması — 422 yanıtında istemci hangi alanın reddedildiğini sizin yazdığınız bayrak adıyla, kararlı error_key'i de katalogdaki açıklamasıyla birlikte yazar. 409 onay gerektiren komutta hazır --yes satırını verir; 429'da Retry-After süresi kadar bekler. Kabuk tamamlaması alan, fiil, bayrak ve enum değerlerini tamamlar ve çevrimdışı çalışır.
Gizli parametreler komut satırına yazılmaz — Birkaç komut bir sır alır — örneğin Paraşüt muhasebe entegrasyonunu bağlamak o sistemin istemci kimlik bilgilerini ve parolasını ister. lg böyle bir değeri bayrak olarak asla kabul etmez, çünkü kabuk geçmişine ve ps çıktısına düşerdi: yankısız olarak sorar ya da ---file=YOL ile dosyadan veya stdin'den (---file=-) okur ve yalnız bellekte tutar. Zorunlu parametresi gizli olan bir komut yalnız lg'den çalışır: sohbetten, MCP'den ya da lg batch içinden çağrılırsa SECRET_REQUIRES_CLI ile reddedilir. Denetim defteri değeri daima *** olarak yazar.
API anahtarı ile bağlanma
Bir ERP, CRM, betik ya da yapay zekâ ajanı Logistivo'ya panelden ya da lg keys create ile üretilmiş bir entegrasyon anahtarıyla bağlanır. Anahtar gerçek bir ekip üyesi adına çalışır: o kişinin rolü komut listesini, anahtarın yetki düzeyi işin ağırlığını belirler; o kişi ekipten ayrılınca anahtar da kapanır. Sentetik bir "servis hesabı" yoktur ve açılmayacaktır — çok kiracılı izolasyon kullanıcıya bağlıdır, sahipsiz bir köprü ise sessizce yıllarca yazmaya devam eden köprüdür.
1. Panelden anahtar üretin — Ayarlar › Entegrasyon anahtarları › Yeni anahtar. Bir ad verin ("ERP gece senkronu"), kapsamı ve yetki düzeyini seçin, isterseniz süreyi kısaltın. Anahtar yalnız bu ekranda, bir kez gösterilir; sunucu saklamaz. Kaybederseniz Yenile ile yenisini üretirsiniz — eski anında geçersiz olur.
2. Terminalden bağlanın — lg login --api-key ile anahtar doğrulanır, kimlik ve kapsam ekrana yazılır, komut kataloğu indirilir. lg whoami hangi kullanıcı, firma, rol ve kapsamla çalıştığınızı sunucuya sorarak gösterir. lg logout anahtarı sunucuda da iptal eder; onay kodu oturumunu da sunucuda kapatır (yalnız parola oturumundaki lg logout bunu yapamaz).
3. Ya da doğrudan HTTP — Anahtar, Authorization: Bearer başlığında taşınan bir erişim jetonudur; aşağıdaki üç komut ucuyla doğrudan kullanılır. Sunucu veya CI ortamında LOGISTIVO_TOKEN değişkenine koyun; değişken doluyken yapılandırma dosyası hiç okunmaz.
4. Ya da anahtarları terminalden yönetin: lg keys — lg keys panel ekranının terminal ikizidir: aynı uçlar, aynı kapı (ekip yönetimi yetkisi ve bir anahtarla çağırıyorsanız yönetici düzeyli anahtar). create, rotate ve transfer yeni jetonu bir kez döndürür: --save-profile=AD ile doğrudan yerel bir profile yazılır ve hiç ekrana basılmaz; aksi halde lg onu bir kez basar. --json kipinde jeton yalnız --show-secret eklerseniz gövdeye girer; iki bayrak da yoksa --json çağrısı istek gönderilmeden reddedilir, jeton bir betik çıktısına sessizce düşmesin diye. rotate, transfer ve revoke onay ister (--yes); anahtar tam adıyla ya da uuid'siyle seçilir, asla tahminle. Yetki düzeyi yenilenen ya da devredilen anahtara aynen taşınır.
Kapsam yalnız komut kataloğunda değil, hesabın TÜM API yüzeyinde zorlanır: yalnız-okuma bir anahtar okuma isteklerini (GET/HEAD/OPTIONS) geçirir, diğer her yazma isteği 403 forbidden döner. İki bilinçli istisna vardır ve ikisi de daha ince bir kapıyla korunur: komut yürütme ucu (kararı komutun read_only bayrağı verir, çünkü yazmayan komutlar da POST ile çağrılır) ve anahtarın kendini iptal etmesi (lg logout, yalnız-okuma anahtarında da serbest). Kapsam, alan izinleri ve yetki düzeyi birbirinden bağımsız üç eksendir ve üçünün de geçmesi gerekir: okuma anahtarı yönetici düzeyinde bile yazamaz, çalışan düzeyli yazma anahtarı ekip yönetemez, loads:write alan izni yönetim işini açmaz. Anahtarı ihtiyacınızı karşılayan en dar yetkili üye adına üretin: hangi kayıtları görebileceğinizi rol belirler.
read — Komut kataloğu ve yazmayan komutlar (liste, arama, önizleme). Yazan bir komut 403 forbidden döner — onay kapısından önce; yalnız-okuma anahtarı 409 bile görmez. Gece senkronu ve raporlama için doğru seçim.
write — Tüm komutlar. Onay gerektiren komutlar yine 409 ile onay ister; confirm: true (CLI'da --yes) aynen çalışır. Kapsam onay kapısını gevşetmez.
employee — Her yeni anahtarın varsayılanı: çalışan düzeyi. Günlük operasyon: yük, talep, teklif, sefer, filo ve filo belgeleri, evrak, cari — yönetim izni istemeyen her komut, artı filo izinleri. Daha fazlasını isteyen bir komut 422, error_key INSUFFICIENT_KEY_LEVEL ve required_key_level: manager ile döner; karşılık gelen REST ucu aynı anahtarla 403 verir. ERP gece senkronu, telematik köprüsü ya da operasyon betiği için doğru düzey.
manager — Yönetici düzeyi: anahtarın adına çalıştığı kişinin yapabildiği her şey, yönetim dahil — ekip üyeleri ve roller, firma ayarları, entegrasyon anahtarları, banka hesapları ve doğrulaması, kayıtlı kartlar, firma ilişkileri, satış ortağı ödemeleri. Yönetici anahtarı kişinin sahip olmadığı bir yetkiyi asla eklemez — ekip yönetimi izni yoksa yine ekip yönetemez. Yetki düzeyi gelmeden önce var olan anahtarlar yönetici düzeyindedir; yani eskisi gibi davranırlar.
Anahtar başına bir entegrasyon — CRM ve ERP aynı anahtarı paylaşırsa birini kesmek için ötekini de kesmeniz gerekir. Her köprüye ayrı anahtar verin; liste zaten adıyla gösterir.
Yenile (rotate) — Yeni bir jeton üretir ve eskisini anında iptal eder; kalan süre korunur. Sızıntı şüphesinde ve düzenli aralıklarla kullanın. Entegrasyon yeni jetonla güncellenene kadar 401 alır.
İptal — Anahtar kalıcı olarak kapanır; geri alınamaz, gerekirse yeni anahtar üretilir. Anahtarın adına çalıştığı üye ekipten çıkarılır veya pasifleştirilirse anahtar da kendiliğinden düşer.
Süre ve sınır — Varsayılan geçerlilik 180 gündür; üretirken kısaltabilirsiniz, uzatamazsınız. Bir kullanıcının en fazla 10 aktif anahtarı olur. Son kullanım zamanı listede görünür; hiç kullanılmamış anahtar bunu açıkça söyler.
Kim yönetir — Anahtar üretme, yenileme, devretme ve iptal ekip yönetimi yetkisi olan yöneticilere açıktır — ekip üyesi ekleme/çıkarma ile aynı kapı — ve bir entegrasyon anahtarıyla yapılıyorsa o anahtar yönetici düzeyinde olmalıdır. Yönetici bir anahtarı başka bir üye adına da üretebilir; köprü için dar rollü ayrı bir üye önerilir.
İlk on dakika: panelden ilk çağrıya
Bir entegrasyonun en pahalı dakikaları ilk on dakikadır. Aşağıdaki dört adım o yolu sırayla kurar; panelde aynı sıra bir sihirbaz olarak da vardır (Ayarlar › Entegrasyon › Kurulum sihirbazı) ve sihirbaz burada anlatılan uçların birebir aynısını çağırır. Sihirbaza erişimi olmayan bir geliştirici bu bölümü okuyarak aynı yere varır.
Dört adımın hiçbiri "gönderdim" ile bitmez. Anahtar gerçekten çalışıyor mu sorusunun cevabı istek defterinde, webhook gerçekten ulaşıyor mu sorusunun cevabı teslimat defterindedir; ikisi de panelde ve lg'de açıktır. Ölçülmeyen bir kurulum, çalıştığı sanılan kurulumdur.
1. Ne yapacağını seç — kapsamı önce kur — Anahtarın neyi görebileceğine SONRA karar vermek yoktur: kapsamı üretim anında seçersiniz. İki eksen var. Kaba kapsam (read / write) yalnız "yazabilir mi" sorusuna bakar. İnce kapsam (alan izinleri: loads:read, invoices:write) hangi alanlara dokunabileceğini söyler ve verildiği anda anahtar fail-closed çalışır — seçmediğiniz her alan ve hiçbir alana eşlenemeyen her uç 403 döner. Panelde alan listesi elle yazılmış bir liste değildir; rolünüzün canlı komut kataloğundan üretilir ve her alanın kaç komut, kaç REST ucu açtığını yanında gösterir. Komut kataloğu, "kimim" (current) ve "oturumu kapat" uçları kapsamdan her zaman muaftır: bir anahtar kendini daima tarif edebilmeli ve kapatabilmelidir. Üçüncü eksen yetki düzeyidir: çalışan (varsayılan) günlük operasyonu yürütür, yönetici ayrıca ekip, ayarlar, anahtar ve para işlerini yapar. Köprü yönetim işi yapmıyorsa çalışanı seçin.
2. Anahtarı üret — jeton bir kez gösterilir — Ayarlar › Entegrasyon › Yeni anahtar. Bir ad verin ("ERP gece senkronu"), anahtarın kimin adına çalışacağını ve yetki düzeyini seçin, isterseniz süreyi kısaltın. Ham jeton yalnız bu yanıtta döner; sunucu onu saklamaz, panelde "tekrar göster" yoktur. Kaybederseniz Yenile ile yenisini üretirsiniz ve eski anında geçersiz olur. Jetonu sürüm kontrolüne, CI günlüğüne veya bir sohbet penceresine yazmayın; hedef sistemin gizli değer deposuna koyun.
3. İlk çağrıyı yap — ve GERÇEKTEN geldiğini gör — İki istek yeter. Birincisi kimliğinizi doğrular (kapsamdan muaftır, her anahtarda çalışır): scope beklediğiniz mi, status active mi, expires_at yaklaşıyor mu. İkincisi seçtiğiniz alandan gerçek veri okur. Geçtiyse kimlik, kapsam, e-posta kapısı ve ağ yolu doğru demektir. Geçmediyse tahmin etmeyin: anahtarın kendi istek defteri hangi ucun hangi kodla reddedildiğini ve kararlı hata anahtarını (INSUFFICIENT_SCOPE, IP_NOT_ALLOWED, KEY_ACTOR_BLOCKED …) satır satır gösterir. Panelde bu defter "Son istekler" penceresidir, terminalde lg logs. Sihirbaz da tam olarak bu deftere bakar ve ilk başarılı çağrıyı görene kadar adımı yeşile çevirmez.
4. Webhook'u kur — ve imzayı doğrulamadan hiçbir şey yapma — Olayları beklemek, dakikada bir sormaktan ucuzdur. Bir https adresi kaydedin, ilgilendiğiniz olayları seçin ve aboneliği anahtarınıza bağlayın: anahtar iptal edilirse gönderim de susar. Gizli değer yalnız oluşturma anında, bir kez gösterilir. Alıcı ucunuz ilk iş olarak imzayı doğrulamalıdır: imzalanan dize "{t}.{ham gövde}" ve algoritma HMAC-SHA256'dır; zaman damgası imzanın İÇİNDEDİR, bu yüzden 300 saniyeden eski bir isteği imzası doğru olsa bile atın. Karşılaştırmayı sabit zamanlı yapın ve gövdeyi yeniden serileştirmeyin — JSON'u parse edip yeniden yazdığınız anda imza tutmaz. Panelden "Test gönder" ile gerçek imzalı bir ping atabilir, teslimatı deneme deneme görebilirsiniz.
Kum havuzu: yazmayı canlıya dokunmadan deneyin
Ön uçuş (dry_run) bir komutun ne YAPACAĞINI söyler; ama idempotency'nin gerçekten tekrar oynatıp oynatmadığı, webhook'un gerçekten teslim edilip edilmediği, hata dallarının nasıl göründüğü ve kredinin nereden düştüğü ancak GERÇEK bir yazmada görülür. Kum havuzu bunun için var: firmanızın ikizi olan ayrı bir kiracı, aynı kod, aynı komut kataloğu — ama canlı defterinize dokunmayan.
Kum havuzu bir istek bayrağı değil, bir KİRACIDIR. Firmanız için açılan ayrı bir Logistivo firması: kendi kullanıcısı, kendi paketi, kendi kredi defteri, kendi webhook abonelikleri. Ortam anahtarın firmasından TÜRETİLİR, çağıran veremez; yanlış profil seçseniz bile istek sunucuda 403 ENVIRONMENT_MISMATCH ile durur. Bu yüzden "kum havuzuna yazdım sandım, canlıya yazmışım" hatası yapısal olarak mümkün değildir.
Yüzey birebir aynıdır — ölçüldü: kum havuzu anahtarının çizdiği katalog, canlı anahtarın çizdiğinin aynısıdır (bir müşteri anahtarında iki tarafta da 646 komut). Kum havuzunda çalışan bir köprü canlıda da çalışır; öğrendiğiniz hiçbir şeyi ikinci kez öğrenmezsiniz.
Kum havuzu boş açılmaz: içinde üretilmiş (kopyalanmış DEĞİL) tohum veri bulunur — cariler, iki yönlü yükler ve talepler. Adlar açıkça uydurmadır ve e-postalar @sandbox.invalid alanındadır; hiçbir gerçek kiracının satırı okunmaz, klonlanmaz ya da örnek alınmaz.
"Sıfırla" düğmesi bilerek YOKTUR ve hiçbir kayıt, dosya ya da evrak silinmez. Temiz bir başlangıç istiyorsanız yenileme yeni bir nesil açar, eskisi emekli olarak durur. Birikmiş birkaç yüz prova satırının maliyeti, yanlış kiracıya bağlanmış bir silme rutininin maliyetinin yanında sıfırdır.
1. Kum havuzunu açın — Firma başına bir kum havuzu. Uç, ekip yönetimi yetkisi (team.manage) ister — yani bunu firmanızda yönetici bir kullanıcı yapar. Zaten varsa aynı uç GET ile durumu döner: firma kimliği, kalan kredi, aktif anahtar sayısı, abonelikler, nesil geçmişi ve tavanlar.
2. Kum havuzu anahtarı üretin ve ikinci profil olarak bağlayın — Anahtar kum havuzunun kendi köprü kullanıcısı adına üretilir ve environment: sandbox damgasıyla döner; ham jeton yalnız bu yanıtta bir kez görünür. lg tarafında canlı anahtarınızı silmeyin — ikisini AYRI PROFİL olarak tutun; --sandbox ve --live tek koşuluk seçicilerdir.
3. Gerçekten yazın — Burada --dry-run'a gerek yok; amaç tam olarak yazmak. Aynı idempotency anahtarını iki kez gönderin ve ikinci yanıtın status: replayed döndüğünü görün — kum havuzunda ölçülen sonuç budur. Onay kapısına bilerek onaysız çağrı yapıp 409 gövdesini okuyun, kapsam dışı bir komut deneyip ret gövdesini görün. Bunların hiçbiri canlı defterinizde iz bırakmaz: aynı tur içinde canlı bakiyeniz değişmeden kalır.
4. Canlıya geçmeden önce kontrol listesini okuyun — Go-live ucu, kum havuzunda GERÇEKTEN yaptıklarınıza bakarak cevap verir: yazma denediniz mi, hata dallarını gördünüz mü, webhook teslim edildi mi, alıcı adresini prova adresinden değiştirdiniz mi, anahtara süre koydunuz mu. Her madde pass / todo / unknown döner. Aynı yanıt, çağırdığınız komutlardan türetilmiş bir KAPSAM ÖNERİSİ de taşır — canlı anahtarınızı ihtiyacınız kadar dar üretmek için kullanın.
Kredi ve fatura — Kum havuzunun kendi kredi defteri vardır ve canlı bakiyeniz değişmez. Bu bir kontrol değil bir yapıdır: kredi firma bazında sayılır, kum havuzu ayrı bir firmadır. Kum havuzu ücretsiz paketle açılır, tahsilat yöntemi yoktur ve aylık tahsilat penceresinin dışındadır — faturaya hiçbir yoldan görünmez.
Pazar yeri — Kum havuzunda açtığınız bir talep gerçek nakliyecilerin ekranına DÜŞMEZ ve onların e-posta/push kutusuna GİTMEZ; siz de gerçek talepleri görmezsiniz. Bölme simetriktir ve iki ayrı sorguda birden uygulanır: talebin kime GÖRÜNECEĞİ ile kime GÖNDERİLECEĞİ ayrı sorulardır.
Webhook — Abonelik de ortam damgası taşır. Kum havuzu olayı canlı aboneliğe teslim edilmez, canlı olay kum havuzu aboneliğine gitmez; damgası kaymış bir abonelik için teslimat hiç açılmaz. Abonelik tavanı firma başına olduğu için prova abonelikleriniz canlı kotanızdan düşmez.
Tohum veri — Kum havuzunun içindeki örnek kayıtlar ÜRETİLİR, gerçek kiracılardan kopyalanmaz. Tohum idempotenttir: ikinci çağrı sizin kendi kayıtlarınızın üstüne ikinci bir tohum bindirmez.
Aynı katalog — Rolünüz neyse kum havuzunda da odur ve komut listesi birebir aynıdır — ölçüldü, iki tarafta da 646 komut. Kum havuzu "kısıtlı bir demo" değil, firmanızın ikizidir.
Bugünkü sınır: webhook aboneliği kum havuzu anahtarıyla yönetilemez — Abonelik uçları ekip yönetimi (team.manage) yetkisi ister; kum havuzunun köprü kullanıcısının bir ekip rolü yoktur, dolayısıyla `lg --sandbox webhooks …` bugün 403 döner. Komut yüzeyinin tamamı çalışır — kısıt yalnız abonelik defterindedir. Kum havuzunda webhook provası yapmak istiyorsanız destekten isteyin; ölçüldü ve açık bir eksik olarak kaydedildi.
GET /api/common/integration-sandbox — Durum: var mı, hangi firma, kalan kredi, aktif anahtar ve abonelik sayısı, nesil geçmişi, tavanlar ve hangi olayı hangi komutla tetikleyebileceğinizi gösteren tetikleyici rehberi.
POST /api/common/integration-sandbox — Kum havuzunu açar (firma başına bir tane, idempotent). team.manage yetkisi ister.
POST /api/common/integration-sandbox/keys — 201 + anahtar ve ham jeton (yalnız burada bir kez). Damga environment: sandbox olarak firmadan türetilir; çağıran veremez.
GET /api/common/integration-sandbox/go-live — Canlıya geçiş kontrol listesi ve kapsam önerisi — kum havuzundaki gerçek trafiğinizden hesaplanır.
POST /api/common/integration-sandbox/renew — Yeni bir kum havuzu NESLİ açar ve eskisini emekliye ayırır.
Komut modeli
Tek bir gramer var ve istisnası yok. Bir komutu nasıl çağıracağınızı bilmek için tek gereken, kataloğun o komut için ne dediğidir.
lg loads list --status=in_transport --limit=20 --json
Bayrak adları şemadaki parametre adlarıdır ve lg iki yazımı da kabul eder: --load_code ile --load-code aynı alana gider (lg help tireli biçimi basar). Bu yüzden bayrağı görünce hangi JSON alanına gittiğini bilirsiniz ve HTTP'ye geçtiğinizde hiçbir ad çevirisi yapmanız gerekmez. Evet/hayır tipindeki bir parametre değersiz yazıldığında true olur (--only_open); tersi --no-only_open ile verilir. Değeri tire ile başlayan bir argümanı --bayrak=değer biçiminde yazın, aksi halde unutulmuş bir bayrak bir sonrakini sessizce değer diye yutar. Dosya alan bir komutta yerel yolun başına @ koyun (--attachment_uuid=@./cmr.pdf) — bkz. Dosya alan komutlar.
lg — İstemci.
loads — Alan — üzerinde çalıştığınız varlık, çoğul.
list — Fiil — o varlığa ne yaptığınız; yalnız bilinçli bir kararla büyüyen kapalı bir sözlükten gelir: basit fiiller (list, get, create, update, delete, search, preview, generate, extract …) ve neyin eklendiğini ya da değiştiğini söyleyen bileşik fiiller (add-document, set-status, assign-driver). lg help bir alanın fiillerini listeler.
--status=in_transport — Parametre — adı JSON Schema'daki parametre adının birebir aynısı, değeri şemadaki tipe uygun. Enum'lu bir alanda geçersiz değer sunucuya hiç gitmez.
--limit=20 — Liste komutlarında satır sayısı. Tavan her komutun parametre açıklamasında yazılıdır — düz bir liste çağrısında genellikle 20, senkron kipinde (cursor ya da updated_since ile) 100'e kadar.
--json — Ham JSON çıktı.
--json — Ham JSON basar. Betikler için tek doğru biçim budur: varsayılan hizalı tablo insan içindir, veriye göre sütun seçer ve düzeni haber verilmeden değişebilir. Bir betiği tablo çıktısını ayrıştırarak yazmayın.
--yes, -y — Onay kapısını geçer (HTTP'de confirm: true). Yalnız ne yapacağını bilen bir betikte kullanın; geri alınamaz bir komutta bu bayrak "geri alma yok" demenin kısa yoludur.
--idempotency-key= — Yazan komutlarda tekrar denemeyi güvenli kılar. Aynı anahtarla ikinci çağrı komutu yeniden çalıştırmaz, ilk sonucu döndürür. Bir yeniden deneme döngüsü kuruyorsanız anahtarı SİZ üretip her denemede aynısını gönderin.
--dry-run — Komut yerine ön uçuş koşar: doğrulama, kapılar ve kredi hesabı çalışır, hiçbir şey yazılmaz (bkz. ön uçuş bölümü). Her komutta ve lg batch'te geçerlidir.
--refresh — Katalog önbelleğini zorla yeniler. lg kataloğu bir saat önbelleğe alır; sunucuya yeni bir komut eklendiğini biliyorsanız beklemek yerine bunu kullanın.
--help, -h — Komutun katalogdan gelen açıklamasını, bütün parametrelerini, tiplerini, enum değerlerini ve zorunlu olanları basar. İstemcinin içinde yazılı bir yardım dosyası yoktur.
--profile=, --sandbox, --live — Bu tek çağrının hangi profille koşacağı. --sandbox ve --live kum havuzu ya da canlı anahtarı taşıyan profili seçer; ortam sunucuda anahtardan türetildiği için uyuşmazlık yanlış yere yazmak yerine 403 ENVIRONMENT_MISMATCH ile durur.
--base-url, --timeout, --verbose, --no-color, --version — Sırasıyla: tek komutluk sunucu değişimi, saniye cinsinden zaman aşımı, istek/yanıt ayrıntısı, ANSI renklerinin kapatılması ve istemci sürümü.
Gerçek örnekler
Aşağıdaki komutların hepsi katalogda bugün var olan komutlardır; adlar ve parametreler uydurulmadı. Çıktılar kısaltılmıştır. Çıktılar `data.result` düzeyini gösterir; HTTP'de aynı nesne `{success, data:{…}}` zarfının içinden gelir (bkz. HTTP komut API'si).
Yolda olan yükler — lg loads list --status=in_transport --limit=20
Tek yükün tam kaydı, ham JSON — lg loads get --load_code=FSK2158 --json
Açık kalmış evrak tutarsızlığı bayrakları — lg loads list-problems --only_open=true --limit=10
Ülkeyi çözün — lg countries search --query=Almanya --json
Çözülen id ile daraltın — lg loads list --receiving_country_id=57 --date_from=2026-09-01 --limit=20
Ürün adından GTİP arayın — lg tariffs search --query="alüminyum profil"
Taslak — lg export-documents create --doc_type=proforma-invoice --currency_code=EUR --json
Üretin (onay ister) — lg export-documents generate --document_id=8412 --yes
İstemci olmadan: HTTP komut API'si
lg bir kolaylıktır, kapı değil. Katalog ve yürütme aynı üç HTTP ucundan geçer; bir ERP veya CRM entegrasyonu doğrudan buraya bağlanır. Kimlik, Authorization: Bearer ile taşınan kişisel erişim token'ıdır. HER yanıt aynı zarfla döner: `{ "success": bool, "data": { … }, "code": "…", "message": { … } }`. Sözleşmenin tamamı `data` içindedir — `contract_version`, `command`, `status` ve komut çıktısı olarak `result`; hata durumunda `error_code`, `error_key` ve `error`. Bu sayfadaki yanıt örnekleri yerden kazanmak için `data` nesnesini gösterir, zarfı değil; kendi kodunuzda `data`'yı açmayı unutmayın. `lg --json` de zarfın TAMAMINI basar, dolayısıyla jq yolları `.data.result…` ile başlar. Tek istisna `/api/public/status`: nöbetçi araçlar ayrıştırmadan alarm kurabilsin diye o uç zarfsızdır.
Onayı 200 + ok:false ile istemek yasaktır ve hiçbir zaman yapılmayacaktır. Sebep basit: istemciler 200'ü başarı sayar; onay isteği 200 ile dönseydi akış sessizce ölür, kimse fark etmezdi. Onay daima 409'dur.
GET /api/common/commands — Rolünüzün gördüğü tüm katalog: contract_version; komut başına name, domain, verb, açıklama, JSON Schema, read_only, confirmation_needed, irreversible, credit_cost, since, deprecated_at, replaced_by, aliases ve erişim alanları key_level, permission, file_params, secret_parameters ve cli_only; üst düzeyde error_keys sözlüğü, rate_limits, idempotency_ttl_hours, katalog rolleriniz, attachments (yükleme) sözleşmesi ve çağırdığınız anahtarın yetki düzeyi. ETag verir; If-None-Match ile 304 döner. ?domain= eski (alias) alan adını da eşler. İstemcinizi bundan çizin; komut listesini elle yazmayın.
GET /api/common/commands/{name} — Tek komutun tam künyesi. name katalogdaki dondurulmuş komut adıdır (list_loads), CLI kimliği değil. Kullanımdan kalkan komut X-Deprecated başlığıyla cevap verir.
POST /api/common/commands/{name} — Yürütme. Gövde: { args, confirm?, idempotency_key? }. Yanıtın HTTP durumu sonucun kendisidir — 200 dışındaki her şey gürültü değil bilgidir. Hatalar error_code (taşıma) ve iş kuralı reddinde error_key taşır.
Dosya alan komutlar
Tablodaki 38 komut bir evrak ya da fotoğraf alır: bir yüke CMR eklemek, bir faturadan GTİP kodlarını okumak, ruhsatından araç oluşturmak, fotoğraflardan palet tahmini çıkarmak, firma belgesi yüklemek, bir faturayı çeki listesiyle karşılaştırmak. Tarayıcıda dosyayı forma bırakırsınız; başka her yerde iki adımdır — dosyayı yükleyin, sonra kimliğini komuta verin.
Adı attachment_uuid ya da attachment_uuids ile biten parametre dosya alır — liste içinde photos[].attachment_uuid, çekte front_attachment_uuid. Bunu ezberlemeniz gerekmez: her katalog satırı tam yolları file_params alanında taşır, şema bu alanları işaretler (format: uuid, x-logistivo-file: true) ve katalog yanıtındaki attachments bloğu yükleme adresini, kabul edilen türleri, boyut sınırlarını ve geçerlilik süresini verir. lg help da gösterir.
Yükleme bir yazmadır, bu yüzden yalnız-okuma anahtarı yükleyemez; yazma kapsamlı her anahtar, hangi yetki düzeyinde olursa olsun yükleyebilir. Yüklemeler anahtarın değil kullanıcınındır: aynı kullanıcının iki anahtarı aynı yüklemeleri görür ve kimse bir başkasınınkini kullanamaz. Bilinmeyen, süresi dolmuş ya da size ait olmayan bir kimlik yalnızca bulunamaz; nedeni açıklanmaz.
Paneldeki sohbet ekleri ile komut yüklemeleri birbirinden ayrı tutulur: asistan sohbetine eklenen bir dosya kimliğiyle bir komuta verilemez, komut yüklemesi de hiçbir sohbet akışında görünmez.
Yükleme bir komut değildir ve tek başına iş etkisi yoktur: bir komut kimliği kullanana kadar verinize hiçbir şey olmaz. Yüklemenin hiçbir zaman onay istememesinin sebebi de budur — kapıyı dosyayı kullanan komut taşır.
1. lg: yerel yolun başına @ koyun — lg dosyayı önce yükler, sonra komutu dönen kimlikle çalıştırır; @ olmadan verilen değer daha önce yüklediğiniz bir dosyanın kimliğidir. Listeler virgülle ayrılmış yol ya da tekrarlanan bayrak, iç içe alanlar JSON alır; komutun tam olarak bir üst düzey dosya alanı varsa --file kısa yoldur. lg her dosyayı göndermeden önce yerelde denetler (var mı, boyutu, türü); lg batch her farklı dosyayı parti koşmadan önce bir kez yükler.
2. HTTP: yükleyin, sonra attachment_uuid verin — Dosyayı multipart/form-data olarak file adlı alanda gönderin. Yeni yükleme 201 döner; aynı kullanıcının aynı dosyayı yeniden yüklemesi 200, status replayed ve aynı kimlikle döner ve hiçbir şey yazılmaz. Bu sayfanın her yerinde olduğu gibi örnek, zarfın içindeki data nesnesini gösterir.
3. MCP: upload_attachment aracı — Bir MCP istemcisi multipart gönderemez; bu yüzden kanal katalogda olmayan tek bir ek araç sunar: upload_attachment bir dosya adı ve base64 içerik alır, aynı attachment_uuid'yi döndürür. HTTP yüklemesiyle aynı servisi, aynı kurallarla çağırır.
Tür içerikten gelir — Dosya adı ve bildirilen tür yok sayılır; saklanan uzantı tespit edilendir. Yüklemede kabul edilenler: jpg, jpeg, png, webp, heic, heif, pdf, xlsx, xls, csv, txt, doc, docx, xml, zip. Ardından her komut çalışmadan önce kendi, daha dar listesini uygular ve kabul edilen türlerle UNSUPPORTED_FILE_TYPE ya da FILE_TOO_LARGE döner.
Boyut — Görseller en fazla 10 MB, diğer dosyalar en fazla 15 MB.
Geçerlilik süresi — Bir yükleme 24 saat kullanılabilir. Sonrasında artık çözülmez (ATTACHMENT_NOT_FOUND) — silinmez. Bir komut bu yüzden düşerse dosyayı yeniden yükleyin.
Aynı dosya, aynı kimlik — Aynı dosyayı (aynı ad, boyut ve içerik) yeniden yüklemek, en az bir saati kaldığı sürece yeni bir kayıt yazmak yerine mevcut kimliği döndürür ve günlük tavanınızdan düşmez.
Günlük tavanlar — Kullanıcı başına günde 300 yükleme (TOO_MANY_FILES) ve firma başına günde 2 GB (DAILY_LIMIT_REACHED); ikisi de retry_after ile 429 döner.
POST /api/common/commands:upload — file alanında multipart yükleme. Yeni yüklemede 201, aynı dosyada 200 ve status replayed. data.attachment döner: attachment_uuid, filename, mime_type, size_bytes, sha256, extraction_status, expires_at ve reused.
Onay kapısı ve geri alınamaz komutlar
Katalogdaki her komut iki bayrak taşır: confirmation_needed (çalışmadan önce açık onay ister mi) ve irreversible (yaptığı iş geri alınabilir mi). İkisi ayrı sorulardır ve ikisi de sunucuda zorlanır — istemcinin kibarlığına bırakılmaz.
Kapı, iş kuralının değil sorumluluğun kapısıdır. Bir teklif vermek navlun sözleşmesine giden ilk adımdır; bir fatura kesmek muhasebe kaydı doğurur; bir stok hareketi defteri değiştirir. Bunların hiçbiri "yanlışlıkla iki kez çalıştırılabilir" olmamalıdır.
Kapı bir komutun ETKİN halinden okunur. Bir komut başka bir komutu sarmalıyorsa (sohbetteki genel yürütücü gibi) kapı sarmalayanın değil, gerçekten koşacak olanın bayrağından gelir. Sabit bir bayrak kullanılsaydı iki hatadan biri kaçınılmazdı: ya fatura komutu onaysız koşardı, ya her ülke araması onay kartı çıkarırdı.
read_only ile kapısızlık aynı şey değildir. Üç ayrı durum vardır: invoices preview hem kapısızdır hem yazmaz; loads create hem kapılıdır hem yazar; invoices create kapısızdır ama yazar — ortada bir taslak oluşur. Ölçüt tek: komut döndüğünde veritabanında bir satır değişti mi?
Bazı işlemler bu kapının arkasında değildir, çünkü hiç komut değildirler: paket satın almak, 3D Secure ile kart eklemek, hukuki metinleri onaylamak ve hesap kapatmak kişinin kendi tarayıcısında olur. Bunlar için lg handoff-links generate bir logistivo.com bağlantısı döndürür — ücretsiz, hiçbir şey yazmayan, sır taşımayan — ve kişi adımı orada tamamlar. Hiçbir bayrak, nasıl verilirse verilsin, bir ödemeyi ya da onayı API çağrısına dönüştürmez.
Bir entegrasyonun onay kapısını her çağrıda otomatik geçmesi teknik olarak mümkündür ama tavsiye edilmez. Doğru desen, kapıyı yalnız gerçekten geri alınabilir olduğunu bildiğiniz komutlarda otomatikleştirmek; geri alınamazları bir insanın kuyruğuna düşürmektir.
1. Çağırın — Onay gerektiren komutu confirm olmadan çağırın. Hiçbir şey değişmez.
2. Özeti okuyun — 409 döner; gövdedeki confirmation.summary insan için yazılmış bir cümledir ("Fatura kesilecek: X A.Ş., 1.200,00 TRY"), ham argüman dökümü değil. Parasal komutlarda yapısal bir önizleme de gelir: kalemler, toplamlar, uyarılar.
3. Onaylayın — Aynı çağrıyı confirm: true (CLI'da --yes) ile tekrarlayın. Geri alınamaz komutlar en fazla bir kez koşacak şekilde işaretlenir.
Ön uçuş: yazan komutu çalıştırmadan etkisini görmek
Bir ERP köprüsünü ilk kez bağlarken en pahalı adım, gövdenin doğru olup olmadığını öğrenmek için komutu GERÇEKTEN çalıştırmaktır: canlı defterde taslak fatura, yanmış kredi, elle temizlik. dry_run bunu bitirir — istek gövdesine bir alan eklersiniz, komut çalışmaz, ne olacağını okursunuz.
Bugün defterde 721 komut var; 327 tanesi okuma yapar ve bir şey yazmaz. Geriye kalan 394 yazan komuttan 346 tanesi onay kapılıdır: confirm olmadan çağrıldıklarında zaten 409 ile ne yapacaklarını anlatırlar. Sorun kalan 48 kapısız komuttaydı — fatura taslağı, ihracat belgesi taslağı, kalem ekleme gibi bir köprünün ilk bağladığı zincir. Onlarda çağırmak yapmaktı.
İkinci boşluk kapılı komutlarda bile vardı: şema doğrulaması onay kapısından SONRA koşuyor. Yani eksik argümanlı bir çağrı önce onay kartını alıyor, onaylıyor ve ancak ondan sonra "şu alan eksik" duyuyordu. Ön uçuş her iki cevabı tek turda verir.
En sık ve en geç fark edilen köprü hatası ise şudur: şemada olmayan bir alan gönderilir (customer_id yerine recipient_contact_id beklenir), sunucu o alanı sessizce atar, komut 200 döner ve kayıt yanlış yere yazılır. Ön uçuş yanıtı bu alanları arguments.ignored altında adıyla listeler; hiçbir hata mesajı bunu söylemez.
Ön uçuş hiçbir şey yazmaz ve bu bir ölçümden önce bir yapı gereğidir: ön uçuş yolu komutun işleyicisine hiç girmez, dolayısıyla sonradan eklenenler dahil her komut için geçerlidir. Yayına alındığında ayrıca ölçüldü: o günkü katalogdaki yazan komutların TAMAMI (iki ayrı argüman kümesi ve iki ayrı rolle, 178 ön uçuş) çalıştırılırken üretilen her SQL ifadesi dinlendi. Tek bir INSERT/UPDATE/DELETE, kuyruğa atılmış tek bir iş, gönderilmiş tek bir e-posta yok; 31 tablonun satır sayısı ve kredi bakiyesi değişmedi.
Çıkış kodu gerçek çağrının alacağı kodun aynısıdır — çalışırdı 0, onay kapısı 4, idempotency çakışması 2, diğer 1 — yani CI adımınızda "lg … --dry-run || exit" anlamlı bir kapıdır.
1. dry_run ile çağırın — İstek gövdesine "dry_run": true ekleyin. Doğrulama, rol ve kapsam kapısı, hedef çözümü ve kredi hesabı koşar; komut koşmaz.
2. would_execute'a bakın — Tek bakılacak bayrak budur. false ise would_stop.at gerçek çağrının nerede duracağını söyler: idempotency, target_precheck, confirmation_gate ya da arguments.
3. Gövdenizi düzeltin — arguments.ignored sessizce atılacak alanları, missing_required eksik zorunlu alanları, would_charge kaç kredi düşeceğini ve bakiyenin yetip yetmediğini söyler.
4. dry_run'ı kaldırın — would_execute true olana kadar tekrarlayın, sonra bayrağı kaldırıp gerçek çağrıyı yapın. Ön uçuşta gönderdiğiniz idempotency anahtarı tükenmediği için gerçek çağrı normal koşar.
HTTP daima 200 — "Komut düşerdi" bilgisi 4xx ile gelmez — ön uçuşun kendisi başarılı oldu, tahmin gövdededir. İstisna, taşıma katmanı reddidir ve gerçek çağrıyla aynıdır: bilinmeyen komut 404, rol/kapsam kapısı 403, kota 429.
read kapsamlı anahtar yazan komutu dry-run da edemez — 403 alır. Ön uçuşun sözü "bu anahtarla, şimdi çağırsam ne olur"dur; yeşil ışık yakıp gerçek çağrıda 403 vermek, ön uçuşun önlemek için var olduğu sürprizin ta kendisi olurdu.
Idempotency anahtarı tükenmez — Ön uçuşta gönderdiğiniz anahtar defterde satır açmaz ve süresi dolmuş bir kilit serbest bırakılmaz. Bu yüzden gerçek çağrıda kullanacağınız anahtarı ön uçuşta da gönderin: serbest mi, tekrar mı oynatır, başka komutla mı çakışır — önceden öğrenirsiniz.
confirm ile birlikte verilebilir — dry_run ve confirm birlikte gönderilirse soru "onaylayacağım, o zaman ne olur" olur. Yine hiçbir şey koşmaz.
Parti provası parti başınadır — commands:batch ucu da dry_run alır ama bayrak partinin kendisine aittir, kaleme değil (kalemde gönderilirse 422). Kalem başına ön uçuş raporu ve partinin toplam kredisi döner; yetersiz bakiye partiyi reddetmez, raporlar.
Bedava değildir — Her ön uçuş gerçek sorgular koşturur (önizleme, bakiye) ve hız sınırı kovasından düşer. Katalogun tamamını her deploy'da geçirmeyin; değiştirdiğiniz komutları geçirin.
Idempotency: tekrar denemek neden çift kayıt üretmez
Bir ERP hata mesajını okumaz, ekranı görmez ve zaman aşımından sonra aynı isteği tekrar gönderir. Bu bölüm tam olarak o davranış için var.
idempotency_key verilen bir çağrı en fazla bir kez koşar. İkinci çağrı komutu yeniden çalıştırmaz; defterdeki sonucu döndürür ve durumu replayed olur. Ağ koptuğunda, zaman aşımı yaşandığında ya da kuyruk aynı işi iki kez ele aldığında mükerrer fatura yerine ilk sonucu alırsınız.
Anahtar yazan her komutta kullanılmalıdır. Kataloğun read_only alanı bu ayrımı size bedavaya verir: read_only: false olan her komut idempotency anahtarı hak eder.
Tekrar stratejiniz üstel geri çekilme kullanmalı ve her denemede AYNI anahtarı taşımalıdır. Deneme başına yeni anahtar üretmek idempotency hiç kullanmamakla aynıdır. Aynı anahtarı paralel göndermeyin: en-fazla-bir-kez ardışık tekrarlar için garantidir, birbiriyle yarışan iki istek için değil.
Tuzak 1 — başarısızlık da kilitlenir — İlk yürütme iş kuralınca reddedildiyse (failed), aynı anahtarla ikinci çağrı aynı hatayı ve aynı error_key'i döndürür, yeniden denemez. Argümanı düzeltip tekrar denemek YENİ bir anahtar ister. Anahtar bir denemeyi temsil eder, niyeti değil.
Tuzak 2 — büyük sonuç gövdesiz oynatılır — Defter sonucu yalnız 64 KB altındaysa saklar. Daha büyük sonuç replayed durumuyla ama boş gövdeyle döner. Entegrasyonunuz gövdeye değil "replayed" sinyaline güvenmeli, veriyi ilgili get komutuyla çekmelidir.
Tuzak 3 — anahtar tek komuta aittir — Aynı anahtarı farklı bir komutla göndermek 409 idempotency_conflict ve conflicting_command döndürür; hiçbir şey koşmaz, hiçbir şey oynatılmaz. Bir anahtarı iki fiil arasında paylaşan istemci bozuktur ve bunu sessiz bir tekrar oynatmadan değil, hatadan öğrenir.
Tuzak 4 — kilit sonsuza dek değil, 24 saat sürer — 24 saat sonra aynı anahtar yeni bir yürütmedir. Ağ tekrarları dakikalar içinde gelir; bir ERP'nin yıllık tekrar eden belge numaraları sonsuza dek "replayed" kalmamalıdır. Katalog pencereyi idempotency_ttl_hours olarak yayınlar.
Tuzak 5 — sunucu hatası anahtarı kilitlemez — 5xx server_error bir iş kuralı reddi değildir: anahtar bağlanmaz, aynı anahtarla tekrar deneme komutu gerçekten koşturur. Yalnız failed kilitler (tuzak 1).
Kapsam ve biçim — firmanız, herhangi bir dize, tercihen UUID — Benzersizlik (firmanız, anahtar) üzerinde zorlanır: başka bir kiracının INV-1001'i sizinkiyle asla çakışmaz ve sonucunuzu asla oynatamaz. Düz bir UUID ya da yapısı gereği benzersiz bir bileşik kullanın: {ERP-belge-no}:{fiil}.
Artımlı senkron ve sayfalama
Bir ERP/CRM köprüsü “her saat her şeyi yeniden çekmek” yerine değişenleri çeker. Liste komutlarının tamamı — loads list, demands list-own, contacts list, invoices list, teammates list, load-groups list, reservations list, drivers list, tenders list, products search, warehouses search — iki ortak parametre alır ve bir ortak alan döndürür.
Neden offset yok: canlı bir tabloda ofset kayar. İki sayfa arasında eklenen bir kayıt bir satırı atlatır ya da iki kez saydırır ve bunu kimse fark etmez. İmleç ileri yönlü olduğu için araya giren ya da güncellenen kayıt listenin sonuna düşer: hiçbir satır kaybolmaz, hiçbir satır ikilenmez.
Tam ilk çekim de aynı mekanizmadır: updated_since=1970-01-01T00:00:00Z ile başlayın ve next_cursor null olana kadar izleyin. Ayrı bir “dışa aktarım” ucu yoktur çünkü gerekmez.
lg ile aynı şey: lg loads list --updated_since=2026-09-01T00:00:00Z --limit=100 --json, sonra lg loads list --cursor= --json.
Bir sonraki senkron için updated_since değerini gördüğünüz en büyük updated_at yapın. Zaman damgası saniye hassasiyetlidir; saniye sınırındaki bir kayıt iki kez gelebilir — kendi tarafınızda external_ref ya da kodla upsert yaptığınız sürece zararsızdır. updated_since ya da cursor vermezseniz komut sohbet kipinde çalışır: insan sıralaması, en fazla 20 satır, next_cursor null ve truncated “daha var” der. Senkron için o kipi kullanmayın.
Bu bölümün makine okunur hata anahtarları: INVALID_CURSOR, INVALID_UPDATED_SINCE, DUPLICATE_EXTERNAL_REF, EXTERNAL_REF_TOO_LONG, EXTERNAL_REF_INVALID. Hepsi HTTP 422 döner; gövdede error_code: "failed" ve result.error_key bulunur. Metne değil, anahtara dallanın.
updated_since — ISO-8601 zaman damgası (UTC önerilir, ör. 2026-09-01T00:00:00Z). Bu andan itibaren güncellenen kayıtlar. Verildiğinde komut senkron kipine geçer: sıralama sabit (updated_at, id) artan, limit tavanı 100.
cursor — Önceki yanıttaki next_cursor değeri, olduğu gibi. Opak ve imzalıdır: üretmeyin, düzenlemeyin, başka bir firmanın ya da başka bir komutun imlecini kullanmayın; hepsi INVALID_CURSOR ile reddedilir.
next_cursor (yanıt) — Sonraki sayfanın imleci. null ise liste bitmiştir; “daha var mı” sorusunun tek doğru cevabı budur.
total (yanıt) — Filtreye uyan toplam satır sayısı, sayfadan bağımsız. İlerleme göstermek için.
Kendi anahtarınız: external_ref
Artan kayıt numaralarını (invoice_id, contact_id) ERP'nizde iş anahtarı yapmayın; onlar opak ve firmanıza kapalıdır. Yük, talep, cari, fatura, ürün ve depo kayıtları sizin anahtarınızı taşır.
Yazarken verin — loads create, demands create, contacts create ve contacts update, invoices create komutları opsiyonel bir external_ref alır (en fazla 120 karakter) ve yanıtta aynen döndürür.
Okurken kullanın — loads get --external_ref=ORD-2026-0917, invoices get --external_ref=..., contacts get --external_ref=..., demands get --external_ref=... çalışır; liste ve arama komutlarında --external_ref= tam eşleşme filtresidir.
Firma başına benzersizdir — Aynı anahtarla ikinci kayıt 422 ve result.error_key = DUPLICATE_EXTERNAL_REF ile reddedilir; başka bir firmanın anahtarı size “bulunamadı” döner. Büyük/küçük harf ayırt edilmez (ord-1 = ORD-1). Arşivlenmiş kayıt anahtarını tutmaya devam eder; yeniden kullanmak için önce geri alın.
Yazarken idempotency_key de gönderin — Ağ zaman aşımından sonra aynı istek yeniden gönderildiğinde mükerrer kayıt yerine ilk sonuç döner. İkisi birbirinin yerine geçmez: external_ref sizin iş anahtarınız, idempotency_key tek bir denemenin kimliğidir.
Giden webhook: olay olduğunda size POST atarız
Buraya kadar her şey çekmeydi: siz sorarsınız, biz cevaplarız. Bir ERP köprüsünün "yük durumu değişti", "fatura kesildi", "teklif geldi" olaylarını öğrenmek için dakikada bir sorması gerekiyordu. Artık gerekmiyor: bir https adresi kaydedersiniz, ilgilendiğiniz olayları seçersiniz, olay olduğunda o adrese imzalı bir POST gelir.
Push, pull'un YERİNE değil YANINA kondu. Artımlı senkron (updated_since + imleç) olduğu gibi duruyor ve hâlâ doğru araç: ilk dolum, geçmişi toparlama ve "kaçırdım mı" sorusunun cevabı orada. Webhook ise gecikmeyi dakikalardan saniyelere indirir. Sağlıklı bir köprü ikisini birden kullanır — webhook'u tetikleyici, senkronu güvenlik ağı olarak.
Gövde bir SİNYALDİR, veri kopyası değil. Künye gider (kimlik, iş anahtarınız external_ref, durum, zaman); ayrıntıyı kendi anahtarınızla GET ile çekersiniz ve o çağrı zaten kendi yetki kapılarınızdan geçer. Böylece sızıntı yüzeyi künyeyle sınırlı kalır. İki alan bilinçli olarak gövdede YOKTUR: teklifi veren firmanın kimliği (gizli teklifler panelde takma adla görünür; kimliği webhook'a koymak o gizliliği ikinci bir kanaldan delerdi) ve rezervasyon iletişim bilgileri (kişisel veriyi gereksiz bir kanaldan dışarı taşımamak).
Olay adları DONDURULMUŞTUR. Bir adın anlamı değişirse yeni ad açılır, eskisi kullanımdan kaldırma penceresiyle yaşar. Gövdeye yeni alan eklemek sözleşme sürümünü ARTIRMAZ — tüketici bilmediği alanı yok saymak zorundadır.
GET /api/common/integration-webhooks — Defter + olay kataloğu + limitler + başlık adları. Her satır susturma sebebini ve 7 günlük teslimat özetini taşır.
POST /api/common/integration-webhooks — 201 + { webhook, secret, shown_once: true }. Gizli değer yalnız burada.
PATCH /api/common/integration-webhooks/{uuid} — Ad / adres / olaylar / aktiflik. Gizli değere DOKUNMAZ.
DELETE /api/common/integration-webhooks/{uuid} — Kaldırır: satır soft-delete edilir (geçmiş sorgulanabilir kalır), bekleyen teslimatlar iptal olur.
POST /api/common/integration-webhooks/{uuid}/rotate-secret — 201 + yeni gizli değer. Eski değer o anda geçersizleşir.
POST /api/common/integration-webhooks/{uuid}/test — ping olayı — gerçek imzayla, gerçek yoldan, gerçek tekrar takvimiyle.
GET /api/common/integration-webhooks/{uuid}/deliveries — Son teslimatlar: durum, kaçıncı deneme, HTTP kodu, süre, hata künyesi.
POST /api/common/integration-webhooks/deliveries/{uuid}/replay — Tek teslimatı yeniden gönderir: event_id KORUNUR, teslimat kimliği yenilenir, gövde aynen kopyalanır.
Olay kataloğu
Aşağıdaki 13 olayın her birinin arkasında GERÇEKTEN yayılan bir olay sınıfı vardır. Katalogda "olsa güzel olurdu" diye bir ad yoktur: ilan edilmiş ama hiç tetiklenmeyen bir olay, entegratörün sonsuza kadar beklediği bir olaydır ve arızası sessizdir. Bu tablo da elle yazılmadı — sayfa her açıldığında canlı katalogdan çizilir.
invoice.payment_recorded bilinçli olarak YOKTUR: o olay sınıfı kodda duruyor ama hiçbir yerden yayılmıyor. Tahsilat olayı, sınıf gerçekten yayılmaya başladığı gün eklenecek — daha önce değil. Bir olayı erken ilan etmek, onu hiç eklememekten kötüdür.
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)
İmza doğrulama
Her istek X-Logistivo-Signature başlığı taşır: t=,v1=. İmzalanan dize "." ve algoritma HMAC-SHA256'dır. v1 öneki şemayı sürümlenebilir tutar: yarın ikinci bir şema gelirse başlık t=…,v1=…,v2=… taşır ve siz bildiğinizi seçersiniz.
Node ve saf PHP için, bağımlılığı olmayan iki referans alıcı yayınlıyoruz. İkisi de yukarıdaki dört kuralı uygular ve --selftest ile kendini sınar: geçerli imza, kurcalanmış gövde, yanlış gizli değer, pencere dışı damga, bozuk başlık, yeniden serileştirme tuzağı ve iki tür tekrar (aynı teslimat / aynı olgu). Doğrulayıcı bizim de kullandığımız kodun birebir karşılığıdır — yayınladığımız sözleşmeyi kendi testimizde de tüketiyoruz.
Gövdeyi HAM hâliyle doğrulayın — İmza baytların üzerinden hesaplanır. Gövdeyi çözüp yeniden serileştirmek (JSON.stringify(req.body), json_encode($request->all())) aynı VERİYİ farklı BAYTLARA çevirir ve imza o an tutmaz. Node'da tuzak sayı biçimidir (kablodaki 1.50 → 1.5; büyük tam sayılarda veri kaybı), PHP'de karakter kaçışıdır (/ → \/, İ → \u0130). Express'te express.raw, Laravel'de $request->getContent(). Bu, alıcı yazarken yapılan EN SIK hatadır.
Zaman damgasını denetleyin — t imzanın İÇİNDEDİR. Yalnız imzayı doğrulamak, ağı dinleyen birinin geçerli bir isteği saatler sonra tekrar oynatmasına izin verir; alıcı bunu doğrulanmış bir olay sayardı. |now − t| > tolerans olan isteği imzası doğru olsa bile atın. Önerilen pencere 300 saniyedir.
Sabit zamanlı karşılaştırın — hash_equals / timingSafeEqual. == ile karşılaştırmak imzayı bayt bayt tahmin ettirir.
event_id ile tekilleştirin, id ile değil — event_id OLGUNUN kimliğidir: aynı olay iki aboneye giderse ikisinde de aynıdır ve yeniden gönderimde de KORUNUR. id (= X-Logistivo-Delivery) o GÖNDERİMİN kimliğidir ve yeniden gönderimde değişir. "Bu işi zaten gördüm mü" sorusu event_id ile cevaplanır; id ile cevaplanırsa bir replay aynı işi ikinci kez koşturur.
Teslimat, tekrar ve susturma
Alıcınız her zaman ayakta olmayacak. Ray bunu varsayar: geçici arıza tekrar takvimine girer, kalıcı arıza aboneliği susturur ve susturmanın SEBEBİ daima yazılır.
Susturma sebebi makine okunur ve kararlıdır (delivery_failures, endpoint_gone, unsafe_target, key_revoked, by_user) ve hem panelde hem `lg webhooks list` çıktısında görünür. Sebepsiz susturma, "neden gelmiyor" sorusunu cevaplanamaz bırakırdı. Yeniden açmak sayacı ve damgayı sıfırlar.
Adresi siz yazarsınız, isteği BİZİM sunucumuz yapar. Kapı olmasaydı, bir bulut meta-veri adresi yazan kiracı ağımızın içinden istek attırabilirdi. Bu yüzden adres hem kayıt anında hem HER teslimatta denetlenir:
Zaman aşımı — toplam 8 sn, bağlantı 4 sn — yavaş bir alıcı worker'ı işgal etmemeli. İşi kuyruğa koyup hemen 2xx dönün.
Tekrar takvimi — 60 · 300 · 1800 · 7200 · 21600 saniye → 6 deneme, yaklaşık 8,6 saatlik pencere.
Tek kalıcı hata: 410 Gone — "beni sil" demektir; tekrar denenmez, abonelik hemen susturulur. Bir imza hatasında ASLA 410 dönmeyin.
Diğer tüm hatalar — 4xx dahil HEPSİ tekrarlanır. Bir iş olayını kaybetmek birkaç fazla istekten pahalıdır: WAF kuralı güncellenirken 403 dönen bir alıcı, 4xx'i kalıcı sayan bir rayda "fatura kesildi" olayını sessizce kaybederdi.
Retry-After — 429 ve 503'te onurlandırılır (tavan 6 saat).
Yönlendirme — TAKİP EDİLMEZ. 302 ile iç bir adrese sıçramak, adres güvenlik kapısını ikinci yoldan delerdi.
Otomatik susturma — ard arda 10 teslimat tükenirse. Ayrıca 410, güvenli olmayan adres ve bağlı entegrasyon anahtarının iptali ANINDA susturur.
yalnız https, yalnız 443/8443 portu, gömülü kimlik bilgisi (https://kullanıcı:parola@…) yasak;
localhost, tek etiketli adlar ve .internal / .local / .svc gibi iç son ekler reddedilir — çözüm sonucuna bakılmadan, niyet reddedilir (split-horizon DNS kapıyı delmesin);
IP literalleri ve DNS çözümünün TÜM kayıtları genel olmalıdır. Bir ad hem genel hem özel bir adrese çözülüyorsa, hangisinin seçileceğini kimse bize sormaz → ad tamamen reddedilir;
teslimat anında adres bir kez çözülür ve bağlantı doğrulanmış adrese çivilenir: DNS yeniden bağlama (rebinding) penceresi kapatılır;
alıcının yanıt GÖVDESİ hiçbir yere yazılmaz (yalnız durum kodu, süre ve kısa hata künyesi) — bir adres kapısı açığının asıl kazancı olan "okuma" yolu kapalı kalsın diye.
"Özel adrese izin ver" diye bir yapılandırma anahtarı bilinçli olarak EKLENMEDİ: böyle bir anahtar bir gün yanlışlıkla açık kalır.
Yalnız abonelik açılışında ve rotate-secret yanıtında BİR KEZ döner. Sunucuda şifreli durur ve bir daha okunamaz; "tekrar göster" yoktur.
lg onu ekrana basar ve orada bırakır — hiçbir yapılandırma ya da önbellek dosyasına yazmaz.
Kaybedilirse yenilenir; eski değer O ANDA geçersizleşir. Kesintisiz geçiş için alıcınız geçiş süresince iki sırrı da denemelidir.
Adres değişikliği gizli değere DOKUNMAZ: "adres değişti" gibi sıradan bir bakım işi, alıcı taraftaki doğrulamayı bozmamalıdır.
Sağlık ve durum: köprü sustuğunda bunu sizden önce kimse fark etmesin
Bir entegrasyon köprüsü nadiren gürültüyle ölür. Genellikle sabaha karşı sessizce susar: jetonun süresi dolar, anahtarın adına çalıştığı kişi ekipten çıkarılır, bir kapsam daraltılır ya da alıcı adresi 403 dönmeye başlar. Sonucu ilk fark eden neredeyse her zaman müşteridir. lg status bu sırayı tersine çevirmek için var.
Tek komut iki soruyu birden cevaplar, çünkü bir kesinti anında ikisi de aynı anda sorulur: platform ayakta mı, ve benim köprüm sağlıklı mı. Platform satırı jetonsuz da çalışır — bir arıza anında ilk şüpheli jetonun kendisidir ve durum sorusunu jetona bağlamak, tam ihtiyaç duyduğunuz anda sizi cevapsız bırakırdı.
Sağlık özeti yeni bir defter tutmaz; zaten var olan üç kaynağı tek cümlede toplar: günlük kullanım sayacı (ne kadar çağırdınız, ne kadarı hataydı), istek defteri (hangi istek, ne zaman, neden reddedildi) ve giden webhook teslimat defteri (olay alıcıya ulaştı mı). Hata oranı daima günlük sayaçtan okunur; ayrıntı defteri tavanlıdır ve tavana dayandığında bunu açıkça söyler.
Aynı sağlık özeti panelde de görünür: Ayarlar › Entegrasyon › Anahtarlar ekranında her satırın yanında bir rozet ve altında gerekçesi durur. Eşikler istemcide hesaplanmaz; sunucu neyi hangi seviyeye koyduysa panel de lg status de onu boyar, böylece iki ekran aynı anahtar için hiçbir zaman farklı bir şey söyleyemez.
Nöbetçi izleyiciniz için jeton gerekmez. Uç yalnız durum kelimeleri döner; sürüm, sunucu adı, kuyruk adı, iş sayısı, hata metni ya da herhangi bir müşteri verisi taşımaz ve taşıyamaz.
Sağlık özeti, her satır için sabit sayıda sorguyla üretilir; anahtar sayısı arttıkça sorgu sayısı artmaz. Ayrıntı için lg logs ile o anahtarın son isteklerini, lg webhooks list ile giden köprünün durumunu okuyabilirsiniz.
SAĞLIKLI — Ölçülen bir arıza yok ve elimizde başarı kanıtı var: defterde başarılı bir çağrı ya da sayaçta hatasız kalan trafik.
DİKKAT — Bir şey bozulmaya başladı: hata oranı ya da ard arda hata serisi eşiği aştı, istekler kapıda reddediliyor, anahtarın süresi doluyor ya da düzenli konuşan bir köprü sustu.
ARIZALI — Köprü şu an iş yapmıyor: anahtarın jetonu istem dışı iptal edilmiş, kapatılmış bir anahtar hâlâ çağrılıyor, ard arda beş hata var, hata oranı yüzde ellinin üstünde ya da webhook aboneliği susturuldu.
KAPALI — Anahtar bilerek kapatılmış ve kimse onu aramıyor. Bu bir karar, bir arıza değil — ve kırmızı gösterilmez.
VERİ YOK — Ölçüm yok: anahtar hiç çağrılmamış ya da ölçümün kendisi başarısız olmuş. İkisi de yeşil değildir.
Sahte yeşil yok. Sağlıklı rozeti ölçülmüş bir başarı kanıtı ister; hiç çağrılmamış bir anahtar yeşil yanmaz, çünkü çalıştığını gösteren tek bir ölçüm yoktur.
Sahte kırmızı yok. Bilerek kapattığınız anahtarlar Kapalı görünür. Her şeye kırmızı demek kırmızıyı anlamsızlaştırır; kapalı bir anahtar ancak kapandıktan sonra hâlâ çağrılıyorsa kırmızı olur — ki o zaman gerçekten bir köprü kırıktır.
Ölçemedik, veri yok demek değildir. Sunucuda bir sorgu başarısız olursa satır sessizce sıfır göstermez; ölçümün yapılamadığını söyler.
Sessizlik daima raporlanır ama körü körüne uyarıya çevrilmez. Ayda bir konuşan bir kapanış köprüsünün otuz saat susması normaldir; son yedi günün en az beşinde konuşan bir köprünün susması arızadır. Ritim ölçülür, varsayılmaz.
Durum sorgusunun kendisi sağlığa karışmaz. lg status'ün çağrıları istek defterinde görünür ama sağlık matematiğine girmez — aksi hâlde kendi başarılı durum sorgunuz hata serisini sıfırlar ve ekran tam da göstermek için var olduğu arızayı gizlerdi.
Her satır ölçülür: veritabanına gerçekten sorgu koşulur, komut kataloğu gerçekten kurulur, kuyruk işçisinin canlı kaydı gerçekten okunur. Hiçbiri varsayılmaz.
Yanıtın kendisi de bir ölçümdür: gövdeyi okuyabiliyorsanız web katmanı ayaktadır.
Tepe seviye yalnız zorunlu bileşenlerden türer. Kuyruk durduğunda cevap degraded olur, down değil — senkron bir API çağrısı kuyruğa ihtiyaç duymaz ve platformu düşmüş ilan etmek yanlış alarm olurdu.
Kuyruğun durumu ölçülemediğinde tepe seviye bozulmaz: bilmemek, bozuk olduğunu ölçmek değildir.
Platform düşükse HTTP 503 döner. İzleme araçları gövdeyi ayrıştırmadan da alarm verebilsin diye gövde zarfsızdır ve yanıt hiçbir ara bellekte saklanmaz.
Hata ve çıkış kodları
Makinenin dallanacağı şey kararlı bir dizedir. error alanındaki metin insanı hedefler, yerelleştirilir ve haber verilmeden değişir — mesaj metnine göre dallanan entegrasyon desteklenmez ve kırıldığında bu bir hata sayılmaz.
İki taksonomi, iki alan. error_code taşıma katmanıdır (yukarıdaki tablo) ve önce ona dallanırsınız. error_key ise failed içindeki kararlı iş kuralı anahtarıdır — INSUFFICIENT_CREDITS, NOT_FOUND, DUPLICATE_CONTACT, INSUFFICIENT_STOCK — katalogda (error_keys) ve aşağıda sözlük olarak yayınlanır. Henüz anahtar üretmeyen komut error_key: null döndürür; sözlükte olmayan bir anahtarı genel bir hata sayın.
idempotency_conflict — HTTP 409 · error_code idempotency_conflict · CLI 2 · Hayır — anahtar daha önce başka bir komut için kullanılmış (conflicting_command). Yeni anahtar üretin.
forbidden — HTTP 403 · error_code forbidden · CLI 3 · Hayır — rol kapısı ya da yazan komutta yalnız-okuma anahtarı.
not_found — HTTP 404 · error_code not_found · CLI 2 · Hayır — yanlış ya da kaldırılmış komut adı.
(şema) — HTTP 422 · error_code invalid_request · CLI 2 · Hayır — istek gövdesi ya da bir argüman şema doğrulamasından geçmedi (errors{}); iş kuralı değil.
401 unauthenticated — Jetonun süresi doldu ya da iptal edildi. Tekrar denemek işe yaramaz; jeton değişmeli.
429 rate_limited — Bu jeton için hız sınırı. Yanıt daima Retry-After ve retry_after, limit, bucket alanlı bir gövde taşır; sabit bir gecikme icat etmek yerine ona uyun. lg bekleyip en çok üç kez yeniden dener, sonra 5 ile çıkar.
5xx server_error / ağ hatası — AYNI idempotency anahtarıyla üstel geri çekilerek tekrar deneyin. Anahtarı değiştirmek, sunucunun bitirmiş olabileceği işi yeniden koşturur. lg üç kez dener (1 s, 2 s, 4 s), sonra error_code olarak network_error ya da server_error vererek 6 ile çıkar.
Kararlılık sözü
Bir entegrasyon sözleşmesinin en pahalı sorusu şudur: “yazdığım kod yarın da çalışacak mı?” Cevabı tek bir sayı verir — katalogdaki contract_version ve her yanıtta gelen X-Contract-Version başlığı. O sayı tek bir soruyu cevaplar: daha önce yazdığın kod, hiç değiştirmeden çalışmaya devam eder mi? Artmadıysa evet. Arttıysa hayır — dayandığın bir şey kaldırıldı ya da daraltıldı.
Çünkü ilan hiçbir şeyi kaldırmaz: ilan gününden sonra da eski kodun aynen çalışır. Sürümü ilanda artırmak tek bir değişiklik için iki sinyal üretir ve seni ilkini yok saymaya alıştırırdı — yani asıl sinyali zayıflatırdı. İlan zaten senin yaptığın çağrının üstünden geliyor: katalog satırında deprecated_at ve replaced_by, o komutun yanıtında X-Deprecated başlığı ve gövdede deprecated bloğu, lg kullanıyorsan stderr'e tek satır uyarı. Yani “kalkıyor” bilgisini öğrenmek için hiçbir şey yapman gerekmez; log'unda zaten duruyor.
İlan ile kaldırma arasında en az iki takvim çeyreği vardır. Pencere boyunca eski komut yanıt vermeye devam eder ve her çağrıda uyarır. Bir CLI adı emekliye ayrıldığında yerine geçen komut o adı alias olarak devralır: pencere boyunca eski ad eski komuta gider, komut kaldırıldığı gün aynı çağrı yenisine düşer — senin istemci sürümü çıkarman gerekmeden.
preview_invoice → get_invoice (ilan 3 Eylül 2026). get_invoice aynı önizleme bloğunu döndürür, üstüne kalemleri, vergi kırılımını, kayıtlı tahsilatları, kalan bakiyeyi ve kendi ERP anahtarınla (external_ref) adresleme imkânını ekler. preview_invoice çalışmaya devam ediyor; lg invoices preview de öyle — ikisi de uyarı basıyor.
artmaz — Yeni komut · yeni opsiyonel parametre · yanıta yeni alan · yeni hata anahtarı · yeni uç — Hiçbir şey yapma. Bilmediğin alanı yok saymak zorundasın; bilinmeyen alanda patlayan bir ayrıştırıcı uyumsuzdur.
artmaz — Emeklilik İLANI: bir komutun kalkacağının duyurulması — Kodun çalışmaya devam eder. Takvimine bir iş yaz — geçiş penceresi en az 6 aydır.
artar — Komut kaldırma · eski CLI adının kaldırılması · yanıttan alan kaldırma · opsiyoneli zorunlulaştırma · enum daraltma — Geçiş penceresini kaçırdın demektir; ilan sana üç ayrı yerden ulaşmıştı.
Komutun API adı (list_loads gibi) sonsuza dek dondurulmuştur; HTTP çağrılarında kullanacağın ad odur.
error_code (taşıma katmanı) ve error_key (iş kuralı) kararlı dizelerdir. Yenisi eklenebilir — sözlükte olmayan bir anahtar görürsen onu genel bir hata say, bu bir kırılma değildir.
HTTP kodu ile gövdedeki status eşlemesi sabittir.
Sürüm numarası asla azalmaz; her yanıtta, gövdesiz 304 ve 429'da bile okunabilir.
Hata ve açıklama METİNLERİ. Yerelleştirilirler ve haber verilmeden değişirler; metne dallanan bir entegrasyon desteklenmez.
Bilmediğin alanların yokluğu. Yeni alan eklemek sürümü artırmaz.
Artan id'lerin iş anahtarı olması. Kendi anahtarını external_ref ile taşı.
Sınıf adından türeyen dinamik hata anahtarları; onlar sözleşmenin parçası değildir.
Komut kimlik tablosu
Aşağıdaki tablo elle yazılmadı: sayfa her açıldığında canlı komut defterinden üretiliyor. Sunucuya bir komut eklendiğinde burada kendiliğinden beliriyor. "Kapı" sütunu bir komutun onay isteyip istemediğini ve geri alınabilir olup olmadığını gösterir; "Roller" sütunu ise onu hangi hesap tiplerinin kataloğunda göreceğini. Rozetler yönetici düzeyli anahtar isteyen, dosya alan ve yalnız lg'den çalışan komutları işaretler.
Komutlar işlevlerine göre ayrı sayfalarda. Bir işlevi seçin; o işin komut tablosu açılır.
API adı (list_loads) dondurulmuştur ve değişmez; HTTP çağrılarında kullanacağınız ad odur. CLI kimliği (loads list) sürüm politikasına tabidir: ilan edildikten sonra ancak sürüm artışı ve geçiş penceresiyle değişir, geçiş boyunca eski çift katalogda alias olarak sunulur. Buradaki açıklamalar komutun kendi künyesinden gelir ve kısaltılmıştır — tam metin, parametre tipleri ve enum değerleri için katalog ucuna bakın ya da lg help çalıştırın. Künye metinleri İngilizcedir: kataloğu asıl tüketen taraf bir istemci ya da bir dil modelidir, ve o metni çevirmek tek kaynağı ikiye bölerdi. Yalnız satış ortağına ait komutlar burada listelenmez; satış ortağı hesabı onları kendi kataloğunda görür.
Yükler ve takip — Yük açma, katılımcılar, belgeler, takip bağlantısı, teslim imzası, ETA ve istisnalar. 115 komut — /tr/developers/cli/loads
Sınır ve gümrük — Sınıra hazırlık kontrolü, sınır ve liman beklemesi, ihracat belgeleri, U-ETDS bildirimi. 42 komut — /tr/developers/cli/border
Talep ve teklif — Taşıma talebi açma, teklif alma ve verme, ihaleler, ağdaki taşıyıcılar. 42 komut — /tr/developers/cli/quotes
Fiyat kartı ve satış teklifi — Anlaşmalı fiyat kartları, teklif şelalesi ve müşteriye satış teklifleri. 57 komut — /tr/developers/cli/pricing
Filo ve sürücü — Sürücüler, araçlar, harcama fişleri, sürücü hesabı, sefer planlama ve Schengen günleri. 115 komut — /tr/developers/cli/fleet
Depo ve stok — Depolar, rezervasyon, rampa randevusu, kapı ekranı, ürünler, stok ve palet. 69 komut — /tr/developers/cli/warehouse
Muhasebe ve fatura — Fatura, gelen fatura denetimi, Paraşüt, yevmiye, tahsilat ve ödeme, kârlılık. 95 komut — /tr/developers/cli/finance
Mesaj ve e-posta — Yük sohbetleri, doğrudan mesajlar, e-posta taslakları ve gelen kutuları, bildirimler. 58 komut — /tr/developers/cli/messages
Tarife ve ticaret önlemleri — GTİP arama, ithalat vergileri, anti-damping önlemleri, karbon raporu. 20 komut — /tr/developers/cli/tariffs
Firmalar ve ekip — Firma rehberi, firma ilişkileri ve belgeleri, alt firmalar, ekip arkadaşları ve davetler. 65 komut — /tr/developers/cli/contacts
Otomasyon ve rapor — Otomasyon kuralları, özel raporlar, Excel ve PDF dosyaları, iş planları. 27 komut — /tr/developers/cli/automation
Hesap ve entegrasyon — Hesap ve dil ayarları, entegrasyon anahtarları, paket, kredi ve cüzdan. 16 komut — /tr/developers/cli/account
ERP ve CRM entegrasyonu — Kimlik: servis hesabı yok, gerçek kullanıcı var
Bir ERP veya CRM, Logistivo'ya panelden çıkarılmış kişisel erişim token'ına sahip gerçek bir firma kullanıcısıyla bağlanır. Sentetik bir servis hesabı — firmasız, kapsam muafiyetli, kimsenin sorumlu olmadığı bir asli kimlik — açılmaz.
Bu bir tercih değil mimaridir. Çok kiracılı izolasyonun tamamı kullanıcının firmasına dayanır; firması olmayan bir kimlik için izolasyon kapsamı işlevsiz kalır ve o token tek bir yanlış sorguda kendisine ait olmayan veriyi görür. İkinci gerekçe denetimdir: defterdeki kullanıcı alanı "bunu kim çalıştırdı" sorusunu bir insana bağlar; servis hesabı bu alanı anlamsızlaştırır ve fatura kesen entegrasyonun sorumlusu kalmaz. Üçüncüsü iptaldir: token bir kişiye aitse, o kişi ayrıldığında entegrasyon da susar. Sahipsiz köprü, sessizce yıllarca yazmaya devam eden köprüdür.
Pratikte: firma panelden normal bir kullanıcı açar (ör. "ERP Köprüsü", sorumlusu adı geçen bir çalışan), ona dar bir rol verir, o kullanıcının oturumundan bir token üretir ve ERP'ye onu koyar.
Bu kullanıcı yetkilendirmede görünür, yetkisi kısılabilir ve token'ı tek başına iptal edilebilir. Yasak olan hesap açmak değil, kiracıya bağlı olmayan hesaptır.
Token başına bir entegrasyon. İki sistem tek token paylaşırsa iptal granülerliği kaybolur: CRM'i kesmek için ERP'yi de kesmek gerekir.
ERP ve CRM entegrasyonu — Sürümleme ve deprecate
Katalog yanıtı bir contract_version tamsayısı taşır; komut satırları since, deprecated_at ve replaced_by alanlarını taşır. Sözleşme sürümü yalnız kırıcı değişikliklerde artar.
Sürüm ARTMAZ: yeni komut, yeni opsiyonel parametre, yanıta yeni alan. Tüketici bilmediği alanı yok saymak zorundadır; bilinmeyen alanda hata veren istemci uyumsuzdur.
Sürüm ARTAR: komut kaldırma veya yeniden adlandırma, yanıttan alan kaldırma, opsiyonel parametreyi zorunlulaştırma, enum daraltma. Eski biçim en az iki takvim çeyreği (6 ay) deprecated_at ve replaced_by ile ayakta kalır.
Deprecate katalogda ilan edilir, sadece bir değişiklik günlüğünde değil. İstemci kendini katalogdan çizdiği için deprecated_at dolu bir komut, hiçbir istemci sürümü çıkmadan uyarı basar ve entegratör uyarıyı log'unda görür.
API adı sonsuza dek dondurulmuştur. CLI kimliği (alan/fiil) ilan edilmeden önce serbestçe değişebilirdi; ilan edildikten sonra ancak sürüm artışı ve geçiş penceresiyle değişir ve geçiş boyunca eski çift alias olarak sunulur.
Pratikte: katalog yanıtı ve X-Contract-Version başlığı sürümü taşır; her komut satırı since, deprecated_at, replaced_by ve aliases (eski alan/fiil çiftleri) taşır. Kullanımdan kalkan komutu çağırmak yine çalışır ve X-Deprecated: name; deprecated_at=…; replaced_by=… başlığı + gövdede deprecated nesnesiyle cevap verir. Katalogda ?domain= eski bir alias alanını güncel komuta çözer.
1. sürümü anlayan bir istemci daha büyük bir sayıyla karşılaşınca uyarı yazıp devam etmelidir; lg tam bunu yapar. Yürürlükteki emeklilikler yukarıdaki kararlılık sözü bölümünde listelenir.
ERP ve CRM entegrasyonu — Kararlı tanımlayıcılar: artan id'yi ERP'ye anahtar diye vermeyin
Dahili artan id'ler opaktır ve kiracıya kapalıdır: başka bir firmanın geçerli id'si size veri değil "bulunamadı" döndürür. Ama opak olmaları onları iş anahtarı yapmaz. ERP'nin kendi kaydında saklayacağı şey bir iş anahtarı olmalıdır.
Yük: code (müşteri kodu, ör. FSK2158). loads get zaten kodla çalışır.
Ülke: ISO 3166-1 alpha-2. countries search kodu geri döndürür.
GTİP / tarife: kodun kendisi — nomenklatür zaten evrenseldir.
Fatura: kesildikten sonra fatura numarası. Taslakta yalnız yüzey id vardır ve taslak id'si bir iş anahtarı DEĞİLDİR — ERP kendi referansını taşımalı, taslak id'sini kalıcı kayda yazmamalıdır.
Ürün, depo, cari: bugün yalnız yüzey id var. Kural yeni komutlar için nettir: yüzey id dönen her komut kiracının kendi iş anahtarını da (SKU, kod, vergi no) döndürür ki ERP kendi tarafında eşleştirebilsin.
ERP ve CRM entegrasyonu — Sayfalama, filtreleme ve artımlı senkron
Liste komutları limit alır ve count döner. Gece senkronu için sözleşme aşağıdakini taahhüt eder; bunu benimseyen bir liste komutu JSON Schema'sında cursor ve updated_since ilan eder, edene kadar onu küçük bir pencere sayın (tavan 20 satır, imleç yok).
İstek: limit (1..komut başına tavan) + cursor (opak, ileri yönlü, sunucu imzalı). offset KULLANILMAZ — canlı tabloda ofset kayar; iki sayfa arasına giren bir kayıt ERP'ye satır atlatır ya da iki kez saydırır, ve bunu sessizce yapar.
Yanıt: { count, total?, next_cursor|null }. count bu yanıttaki satır sayısıdır; next_cursor null ise liste bitmiştir. next_cursor'ı olduğu gibi geri verin — bir sayfa numarası değildir ve sizin kuracağınız bir şey değildir.
Kurcalanmış ya da yabancı bir imleç 422 invalid_request ile reddedilir; imleç onu alan firmaya bağlıdır ve başka bir kiracının verisini sayfalayamaz.
Filtre: JSON Schema'daki adlandırılmış parametreler, AND ile birleşir. Serbest sorgu dili yoktur — bir DSL, savunmak zorunda kalacağımız ikinci bir sorgu yüzeyi olurdu.
Artımlı senkron: updated_since (ISO-8601, UTC) + imleç. Gördüğünüz en yeni updated_at'i saklayıp bir sonraki koşuda geri verin; onsuz her ERP her saat her şeyi yeniden çeker.
Dış referans: yazan komutlar external_ref (sizin belge anahtarınız) kabul eder, firma başına benzersizdir; aynı external_ref ile ikinci bir oluşturma mükerrer kayıt yerine reddedilir, list/get onu döndürür ki kayıtları kendi tarafınızda eşleştirebilesiniz.
ERP ve CRM entegrasyonu — Hız sınırları
Sınır anahtarı jetondur, IP değil: bir ERP tek NAT arkasından gelir, IP tabanlı sınır tüm firmayı tek kullanıcı sayardı. İki anahtarlı iki entegrasyon birbirinin kotasını asla yemez — "anahtar başına bir entegrasyon" kuralının ikinci gerekçesi.
Kimliksiz keşif (public/cli/catalog): dakikada 30. Bir sözlüktür, veri kaynağı değil; köprüyü yazarken bir kez okuyun, üretim döngüsünde asla.
Katalog uçları (GET common/commands, GET common/commands/{name}): jeton başına dakikada 120. Katalog nadiren değişir ve If-None-Match'e 304 döner; her komuttan önce yeniden çekmeyin — lg bir saat önbellekler.
Okuyan komutlar (read_only: true ile POST common/commands/{name}): jeton başına dakikada 120.
Yazan komutlar (read_only: false ile POST common/commands/{name}; bilinmeyen ad da buraya sayılır): jeton başına dakikada 30. Yazma yan etkilidir; kaçak döngü faturalandırılır.
Kredi harcayan komutlar (katalog satırındaki credit_cost sıfır değil — örneğin tariffs inquiry ve export-documents generate): gerçek sınır istek sayısı değil KREDİDİR. Bir 200 yanıtı bir kredi harcamış olabilir.
Panelle paylaşılan, firma başına günlük tavanlar: firmanız dışındaki kişilere e-posta ya da push gönderen komutlar günde 300 dış bildirimden, ücretli konteyner ya da gemi takibi başlatmak günde 100'den düşer. Tavan aşılınca komut retry_after ile DAILY_LIMIT_REACHED döner; dosya yüklemelerinin kendi tavanları vardır (bkz. Dosya alan komutlar).
429 daima Retry-After ve { error_code: "rate_limited", retry_after, limit, bucket } gövdesi taşır; sabit gecikme icat etmek yerine ona uyun. Katalog güncel sayıları rate_limits altında yayınlar.
ERP ve CRM entegrasyonu — Yapılmayacaklar
Bir sözleşmenin en yararlı kısmı çoğu zaman budur: neyin gelmeyeceğini bilmek, mimarinizi ona göre kurmanızı sağlar.
Servis hesabı / kiracıya bağlı olmayan asli kimlik açılmaz.
API ya da sohbet üzerinden ödeme, kart numarası veya hukuki onay yok. Bu adımlar kişinin kendi tarayıcısında kalır; komut size bağlantıyı verir.
İkinci yol açılmaz: ERP için doğrudan veritabanı erişimi, kabuk erişimi ya da tek zorlama noktasını atlayan toplu bir uç yoktur. Rol kapısı, onay kapısı, idempotency ve denetim defteri yalnız orada zorlanıyor.
Hata mesajı metnine göre dallanma desteklenmez; metin yerelleştirilir ve haber verilmeden değişir.
offset ile sayfalama açılmaz.
Yüzey id'nin ERP'de iş anahtarı olarak kullanılması desteklenmez.
Giden webhook bu sözleşmeye sıkıştırılmaz — ama artık VARDIR ve bu sayfada belgelidir (yukarıdaki webhook bölümü). Katalog bir ÇEKME yüzeyidir ve olay akışı AYRI bir sözleşmedir: olay adları ve gövde şeması kendi kurallarıyla sürümlenir, komut kataloğunun sözleşme sürümüne bağlı değildir.
Makine okunur katalog
Bu sayfa insanlar için yazıldı. Bir yapay zekâ asistanı ya da otomatik bir istemci için aynı bilginin kimlik doğrulamasız, yapısal bir kopyası var.
GET /api/public/cli/catalog kimlik doğrulaması istemez ve komutların kamuya açık künyesini döndürür: dondurulmuş API adı, CLI alan/fiil kimliği, açıklama, JSON Schema parametreleri, read_only, confirmation_needed ve irreversible bayrakları, credit_cost ve erişim alanları key_level, permission, file_params, secret_parameters ve cli_only. Kişisel veri, kiracı verisi ya da örnek kayıt döndürmez — yalnız yüzeyin ne olduğunu anlatır.
Bir dış ajan için doğru kullanım şudur: kataloğu oku, kullanıcıya hangi işlerin mümkün olduğunu KENDİ kelimelerinle anlat, ve yürütme gerektiğinde kullanıcıyı kendi token'ıyla kendi ortamında çalıştırmaya yönlendir. Ajan, kullanıcının token'ını istemez, üretmez ve taşımaz.
Logistivo'yu bir yapay zekâ asistanına bağlamak (üyelik ve talep açma akışı) ayrı bir kanaldır ve kendi sayfasında anlatılıyor:
Katalog kimliksizdir; yürütme değildir. Bir komutu ajan adına koşturmanın yolu yoktur — koşan daima kullanıcının kendi kimliğidir.
Logistivo şifresi, doğrulama kodu ya da erişim token'ı bir sohbetten geçmez. Bunları isteyen, üreten veya ileten bir akış kurmayın.
Bir komutun geri alınamaz olup olmadığı katalogda yazılıdır. irreversible: true olan bir komutu kullanıcıya "deneyelim" diye önermeyin.
credit_cost değeri sıfır olmayan komutlar (örneğin tariffs inquiry ve export-documents generate) parasal sonuç doğurur; bunları otomatik döngüde çağırmayın.
Ödeme, kart numarası ve hukuki onay asla bir sohbetten ya da ajandan geçmez. Bunun yerine handoff-links generate bağlantısını önerin; kişi adımı kendi tarayıcısında tamamlar.
Bir kullanıcının anahtarıyla çalışan ajan önce users get çağırmalıdır: rolü, anahtarın yetki düzeyini, etkin izinleri ve bekleyen bir onayın ya da telefon doğrulamasının yazmaları engelleyip engellemediğini döndürür — retleri toplamak yerine önceden kestirin.
Bu sayfanın düz metin ikizi /cli.md adresindedir; markdown'ı HTML'den daha güvenilir ayrıştırıyorsanız onu kullanın.
Makine okunur tanım: OpenAPI 3.1 ve Postman
Yukarıdaki katalog Logistivo'nun kendi biçimidir. Aynı bilgi, araçlarınızın hiç öğrenmeden okuyabileceği iki endüstri standardı biçimde de yayınlanıyor: bir OpenAPI 3.1 tanımı ve bir Postman koleksiyonu. İkisi de elle yazılmıyor — her istekte canlı komut defterinden üretiliyor, dolayısıyla eskiyemiyorlar.
Tanım kataloğun ta kendisidir, ikinci bir gerçeklik değil. Her komut bir POST /api/common/commands/ operasyonu olarak görünür; gövde şeması komutun kendi JSON Schema'sıdır (asistanın gördüğü şemayla birebir aynı), yanıt şeması ortak zarftır, kapı bayrakları (read_only, confirmation_needed, irreversible ve kredi künyesi) x-logistivo uzantısında, iş hatası anahtarları x-error-keys altında durur. Kullanımdan kalkan bir komut deprecated: true ile işaretlidir ve altı aylık geçiş penceresi boyunca çağrılabilir kalır.
Komut yüzeyinin yanında entegrasyon sözleşmesini taşıyan REST uçları da tanımdadır: artımlı senkron sunan 10 liste ucu (updated_since + cursor + limit) ve kendi anahtarınızı (external_ref) kabul eden 7 yazma ucu. Logistivo'nun REST yüzeyi bundan çok daha geniştir; gerisi tanıma BİLEREK konmadı. O uçların gövdeleri ürünün kendi sözleşmesidir ve tahminle yazılmış bir şema, ürettiğiniz istemciyi ilk çağrıda kırardı — üstelik hatayı bizde değil kendi kodunuzda arardınız.
Tanım isteyenin ROLÜNE göre üretilir: başka bir rolün komutu belgeye girmez, çünkü belge bir sözlük değil bir sözleşmedir ve içindeki her operasyonun o jetonla çağrılabilir olması gerekir. Kimliksiz sürüm üç rolün birleşimidir ve orada her satır hangi rollerin göreceğini x-logistivo.roles altında açıkça söyler.
Bize güvenmeyin, doğrulayın: npx @redocly/cli lint logistivo-openapi.json — tanım sıfır uyarıyla geçer.
GET /api/common/spec/openapi.json — Jetonunuzun rolünün OpenAPI 3.1 tanımı. ETag verir; If-None-Match ile 304 döner, yani her derlemede yeniden indirmezsiniz.
GET /api/common/spec/postman.json — Aynı kapsamın Postman v2.1 koleksiyonu; base_url ve token değişkenleriyle, klasörleri komut alanlarına göre hazır gelir.
GET /api/public/cli/openapi.json — Kimliksiz sürüm — üç rolün birleşimi. Jeton almadan önce köprüyü tasarlamak ve maliyetlendirmek için.
GET /api/public/cli/postman.json — Kimliksiz Postman koleksiyonu; ekibinize dağıtabileceğiniz tek dosya.
761 operasyon — 721 komut + 36 REST/kontrol düzlemi operasyonu + 4 katalog ve kimlik ucu. Bu sayfadaki sayılar elle yazılmadı; her istekte canlı belgeden sayılıyor — bir komut eklendiği gün burada da artıyor, üstelik toplamları tutar.
Kimlik şeması — bearerAuth: gerçek bir kullanıcı adına üretilmiş Passport jetonu. read kapsamlı bir anahtar yalnız x-logistivo.read_only: true olan operasyonları çağırabilir; yazma denemesi onay kapısından ÖNCE 403 döner, dolayısıyla salt-okunur bir anahtar hiçbir zaman 409 görmez.
Hata dalları tek tek yazılı — Her operasyon 401/403/404/409/422/429/500 yanıtlarını ayrı ayrı tarif eder. 409'un iki anlamı (onay gerekli / idempotency çakışması) ve 422'nin iki anlamı (şema hatası / iş kuralı reddi) belgede ayrıdır — kod üreteciniz ikisini tek dala indirmez.
Zaman damgası yok — Belge üretim anı taşımaz. Aynı katalog aynı baytı verir; ETag bu yüzden gerçekten işe yarar ve sürüm kontrolüne koyduğunuz tanım her indirmede 'değişmiş' görünmez.
Ürün gövdelerini uydurmadık — REST yazma uçlarında yalnız sözleşme alanı (external_ref) tarif edilir; gövdenin geri kalanı additionalProperties: true olarak açık bırakılır ve okuyucu ürün dokümanına yollanır. Eksik ama doğru bir tanım, tam ama uydurma bir tanımdan iyidir.
Hata anahtarı listesi operasyon başına TAM değildir — x-error-keys yalnız komutun künyesinden kesin olarak çıkan anahtarları sayar ve bunu x-error-keys-exhaustive: false ile söyler. Tam sözlük belgenin kökündedir; tanımadığınız bir anahtarı genel hata sayın. Uydurulmuş bir 'tam liste' sizi default dalını hiç yazmamaya iterdi.
Keşif araçları tanımda yok — search_commands, run_command ve list_capabilities yalnız sohbet döngüsünün içinde çalışır ve HTTP'den çağrılamaz. Tanıma konsalardı kod üreteciniz hiçbir zaman çalışmayacak üç metot yazardı.
Kod üretimi: tanımdan tipli istemci
Tanımı indirdiniz; şimdi ondan çalışan kod üretin. `lg codegen` OpenAPI belgesini okuyup tek dosyalık, bağımlılıksız bir istemci yazar — TypeScript (tip tanımları + ince çağrı sarmalayıcı) ya da PHP (PHPDoc array-shape'li istemci sınıfı). Üretilen dosyada `npm install` yoktur, composer yoktur; TypeScript tarafında `fetch`, PHP tarafında `ext-curl` yeter.
Üretim SİZİN makinenizde olur, bizim sunucumuzda değil. Sebebi tercih değil: tanımı bir kez indirip depoya sabitlerseniz (`lg spec --out=...`) her derlemede aynı komut ağsız ve jetonsuz koşar; CI'ınız bizim ayakta olmamıza bağlanmaz. Üstelik üretilen kod sizin ERP'nizde ÇALIŞAN koddur — onu bir API'den indirmek yerine deponuzda tutmak, her sürümde neyin değiştiğini `git diff`te görmenizi sağlar.
Üretilen istemci Logistivo'nun üç rayını da doğru açar ve bunu tahminle değil belgeden öğrenir: her operasyon `x-logistivo.surface` alanında hangi raya ait olduğunu söyler. Komut rayı `{success, data:{…}}` zarfını açar; REST senkron listesi ZARFSIZ döner ve olduğu gibi verilir (açılsaydı `next_cursor` düşerdi); REST yazma rayı ucun kendi ürün gövdesini döndürür. Genel amaçlı bir kod üreteci bu ayrımı bilmez — bizimki bilir.
Tipler tahmin değil: her komutun argüman arayüzü, asistanın gördüğü JSON Schema'nın ta kendisinden üretilir. Zorunlu alan zorunlu, enum birlik tipi, iç içe nesne iç içe tip olur. Pratik karşılığı şudur: sunucuda zorunlu bir alan varsa onu unutan çağrı CANLIDA 422 almaz, DERLEMEDE durur.
Üretilen dosyaya üretim anı yazılmaz: aynı tanım ve aynı bayraklar aynı baytı verir. Böylece yeniden üretim `git diff`'te gürültü yapmaz ve gerçekten değişen tek şey — sözleşme — görünür kalır.
1. Tanımı sabitleyin — Tanım rolünüze göre üretilir; içindeki her operasyon o jetonla çağrılabilir. Dosyayı deponuza koyun. lg login --api-key= lg spec --out=logistivo-openapi.json
2. İstemciyi üretin — Tek dosya çıkar ve sabitlediğiniz belgedeki HER operasyonu metot olarak taşır: rolünüzün çağırabildiği komutlar, entegrasyon sözleşmesini taşıyan REST uçları ve keşif uçları. Sayı platform toplamı değil SİZİN rolünüzündür — bugün bir müşteri anahtarı 646, bir nakliyeci 621, bir gümrük müşaviri 392 komut metodu üretir. Kimliksiz kamu tanımından üretirseniz üst sınır 761 operasyondur. lg codegen ts --from=logistivo-openapi.json --out=logistivo-client.ts lg codegen php --from=logistivo-openapi.json --out=LogistivoClient.php --namespace="Acme\\Logistivo" # ya da tanımı indirmeden, doğrudan sunucudan: lg codegen ts --out=logistivo-client.ts
3. Doğrulayın, sonra kullanın — Üretilen kod derlenmiyorsa sorun sizde değil bizdedir; tanımın bütünlüğü sunucu tarafında koşulabilir bir kapıyla korunur. npx tsc --noEmit --strict --target ES2022 --module ESNext --moduleResolution bundler logistivo-client.ts php -l LogistivoClient.php
Operasyon başına bir metot — Belgedeki her komut, entegrasyon sözleşmesini taşıyan her REST ucu ve keşif uçları. Rolünüzün belgesinden üretirseniz yalnız çağırabildikleriniz gelir (müşteri 646 komut); kamu tanımından üretirseniz 761 operasyonun tamamı. Sunucuya bir komut eklendiği gün yeniden üretmek onu getirir; beklenecek bir istemci sürümü yoktur.
Argüman tipleri — Her komutun `args` şeması bir arayüz/array-shape olur. Zorunlu alanlar zorunlu, enum'lar birlik tipi. TypeScript tarafında zorunlu bir alanı unutmak derleme hatasıdır; PHP tarafında IDE ve PHPStan aynı şekli görür.
Hata sınıfları — Taşıma taksonomisi (`error_code`) ve iş taksonomisi (`error_key`) ayrı alanlardır; onay kapısı ve hız sınırı ayrı hata tipleridir. Hata anahtarı birliği bilinmeyen değere de açıktır — sunucu yeni bir anahtar ilan ettiğinde kodunuz derlenmeyi bırakmaz, `default` dalına düşer.
Doğru tekrar politikası — Otomatik tekrar YALNIZ güvenli çağrılarda uygulanır: okumalar ve idempotency anahtarı taşıyan yazmalar. Anahtarsız bir yazmanın zaman aşımı 'yazılmadı' demek değildir; istemci onu körlemesine tekrarlamaz. 429'da sunucunun `Retry-After` değeri beklenir, sabit gecikme icat edilmez.
Sonuç gövdeleri tiplenmez — Komut sonuçları `unknown` (PHP'de `mixed`) döner. Sebebi §tanımdakiyle aynı: sonuç şekilleri komutun iş çıktısıdır, sözleşmenin parçası değil. Tahminle yazılmış bir sonuç tipi, ilk alan değişikliğinde sessizce yalan söylerdi.
Üretilen dosya elle düzenlenmez — O bir çıktıdır, kaynak değil. Davranış eklemek istiyorsanız üretilen sınıfı sarın; içine yazdığınız her satır bir sonraki üretimde kaybolur.
Keşif araçları üretilmez — `search_commands`, `run_command` ve `list_capabilities` yalnız sohbet döngüsünün içinde çalışır ve HTTP'den çağrılamaz; tanımda olmadıkları için üretilen istemcide de yoklar. Olsalardı hiçbir zaman çalışmayacak üç metot yazmış olurduk.
Dürüst kapsam
Bu bölümü küçültmek yerine büyütüyoruz. Bir entegrasyon sözleşmesinin değeri, vaat ettiklerinden çok neyi vaat etmediğini net söylemesindedir.
CLI kiracı kullanıcı bağlamında çalışır — Her komut, token'ı taşıyan kullanıcının firması ve rolü altında koşar. Platform operatörü kipi — birden çok firmanın verisine bakan bir yönetim kipi — bu yüzeyin dışındadır ve buradan açılmayacaktır.
Komut listeniz rolünüze göre değişir — Yük sahibi hesabı 646, nakliyeci 621, gümrük müşaviri 392, satış ortağı 55 komut görür. Bir komutu kataloğunuzda görmüyorsanız önce role bakın; listede olup reddediliyorsa anahtarın kapsamına ve yetki düzeyine bakın. Sürücü hesapları bu yüzeye hiç erişmez.
Bazı komutlar kredi harcar — Tarife sorgusu, belge üretimi ve yapay zekâ destekli birkaç komut daha paketinizin kredi bakiyesinden düşer. Her katalog satırı credit_cost {mode, credits} taşır: fixed çağrı başına kesin ücrettir, read_only hiç ücret kesmez, computed ise ücretin çağrıya bağlı olduğu anlamına gelir — credits o zaman null'dır ve gerçek rakam onay kartında görünür. Ön uçuş (dry_run) tek bir çağrının ne kadar keseceğini ve bakiyenizin yetip yetmediğini söyler.
Entegrasyon anahtarları panel sohbetini süremez — Paneldeki yapay zekâ asistanı insanlar içindir. Bir entegrasyon anahtarıyla asistan koşusu başlatmak ya da sürdürmek 403 ile reddedilir; ajanlar komut uçlarını, lg'yi ya da MCP kanalını kullanır — orada her komut anahtarın yetki düzeyiyle koşar ve yazmaları entegrasyon yazması olarak kaydedilir.
Katalog mevcut REST API'nin yerine geçmez — Logistivo'nun web ve mobil uygulamalarını besleyen REST yüzeyi yerinde duruyor ve geriye dönük uyum kuralına tabi. Komut kataloğu onun yerine geçen bir şey değil, FİİLLER katmanıdır: bir işi yapmanın tek ve denetlenen yolu.
Liste komutları bugün küçük pencereler döndürür — Bir liste komutu şemasında cursor ve updated_since ilan edene kadar tavanı 20 satırdır ve imleç yoktur. Verinizin tam kopyasını çıkarmak için tasarlanmamıştır; artımlı senkron komut komut yayılmaktadır.
Sıkça sorulan sorular
Logistivo CLI ne işe yarar?
Logistivo hesabınızdaki işleri terminalden, bir betikten ya da kendi yapay zekâ ajanınızdan çalıştırmanızı sağlar: yük ve sefer, talep, teklif ve ihale, filo, sürücüler ve masrafları, evrak, cari ve iletişim, fatura ve muhasebe, depo ve stok, ekip üyeleri, GTİP ve dampinge karşı vergi sorgusu. Paneldeki her yazma işleminin bir komutu var; ödeme, hukuki onay ve hesap kapatma bilinçli olarak tarayıcıda kalır. Aynı komutlar ERP/CRM entegrasyonu için HTTP ile ve MCP kanalından da çağrılabilir.
Logistivo CLI'da komutlar nasıl adlandırılır?
Biçim lg --parametre=değer şeklindedir. Alan çoğul bir varlıktır (loads, demands, invoices, export-documents), fiil yalnız bilinçli bir kararla büyüyen kapalı bir sözlükten gelir (list, get, create, update, search, set-status, generate ve benzerleri). Bir varlığın bütün fiilleri tek alanda toplanır ve (alan, fiil) çifti katalog genelinde benzersizdir.
CLI'a nasıl kimlik doğrularım?
Etkileşimli kullanımda lg login bir onay kodu gösterir; kodu Logistivo'ya tarayıcıda girdikten sonra onaylarsınız — terminale parola ya da anahtar yazılmaz ve oturum lg logout diyene kadar açık kalıp kendini yeniler. lg login --password (e-posta ve parola) yedek yol olarak durur. Sunucuda ve CI'da panelden ya da lg keys create ile üretilen bir entegrasyon anahtarı kullanın: lg login --api-key onu yerel bir profile kaydeder ya da anahtarı LOGISTIVO_TOKEN ortam değişkenine koyarsınız. HTTP tarafında jeton Authorization: Bearer başlığında taşınır.
ERP entegrasyonu için servis hesabı açabilir miyim?
Hayır. Entegrasyon, panelden açılmış gerçek bir firma kullanıcısının token'ıyla bağlanır. Firmasız sentetik bir kimlik çok kiracılı izolasyonu işlevsiz bırakır, denetim defterindeki "kim çalıştırdı" alanını anlamsızlaştırır ve sahibi ayrıldığında susmayan bir köprü bırakır. Doğru desen, entegrasyona adanmış, dar rollü ve sorumlusu belli bir kullanıcı açmaktır.
Logistivo'nun test (sandbox) ortamı var mı?
Var ve self-servistir: firmanız için ayrı bir kum havuzu kiracısı açılır — aynı kod, aynı komut kataloğu, kendi kredi defteri. Ortam anahtarın firmasından türetilir, istekle verilemez; yanlış profille yaptığınız çağrı sunucuda 403 ENVIRONMENT_MISMATCH ile durur. Kum havuzunda açtığınız talep gerçek nakliyecilere gitmez, kum havuzu olayı canlı webhook aboneliğinize teslim edilmez ve canlı bakiyeniz değişmez. Uçlar: POST /api/common/integration-sandbox (aç), POST /api/common/integration-sandbox/keys (anahtar), GET /api/common/integration-sandbox/go-live (canlıya geçiş kontrol listesi). lg tarafında lg --sandbox ve lg --live tek koşuluk profil seçicileridir.
Betikte lg --json çıktısını nasıl okurum?
Çıktı HTTP zarfının tamamıdır: { "success": bool, "data": { "contract_version", "command", "status", "result" }, "code", "message" }. İş verisi .data.result altındadır; liste komutlarında satırlar .data.result., sayı .data.result.count, sonraki sayfa .data.result.next_cursor olur. Yani doğru jq yolu lg loads list --json | jq -r '.data.result.loads[].load_code' şeklindedir. Zarfı atlayan bir yol hata vermez, sessizce null döner — bir nöbetçi betikte bu, hiç susmayan bir alarma dönüşür. Tek istisna /api/public/status ucudur: o gövde bilerek zarfsızdır.
Aynı isteği iki kez gönderirsem çift kayıt oluşur mu?
idempotency_key gönderdiyseniz hayır. Aynı anahtarla ikinci çağrı komutu yeniden çalıştırmaz, ilk sonucu döndürür ve durumu replayed olur. Anahtarın UUID olması ve her yeniden denemede AYNI kalması gerekir; anahtarı yenilemek idempotency'yi kullanmamakla aynı şeydir.
--yes ne yapar?
Onay kapısını geçer. Onay gerektiren bir komut --yes olmadan çağrıldığında hiçbir şey değişmez: sunucu ne yapacağını bir cümleyle özetler, geri alınamaz olup olmadığını söyler ve durur (HTTP 409, CLI çıkış kodu 4). Aynı komutu --yes ile tekrarladığınızda iş yapılır.
Bir komutun başarısız olduğunu betikte nasıl anlarım?
Çıkış koduna bakın, mesaj metnine değil: 0 başarı, 1 iş kuralı reddi, 2 komut/argüman hatası, 3 yetki veya kimlik hatası, 4 onay gerekli. HTTP tarafında karşılıkları sırasıyla 200, 422, 404, 403 ve 409'dur ve gövdedeki error_code alanı kararlıdır. Hata METNİ yerelleştirilir ve haber verilmeden değişir.
Hangi komutların var olduğunu programatik olarak nasıl öğrenirim?
Kimlik doğrulamasız keşif için GET /api/public/cli/catalog, hesabınızın gerçekten görebildiği liste için GET /api/common/commands. İkisi de her komutun JSON Schema parametrelerini döndürür; istemcinizi bundan çizin, sabit bir komut listesi gömmeyin.
Yeni bir komut eklendiğinde istemcimi güncellemem gerekir mi?
Hayır. İstemci komut listesini kataloğdan çeker; sunucuya eklenen komut yeni bir istemci sürümü çıkmadan görünür. Güncelleme yalnız sözleşme sürümü artan kırıcı bir değişiklikte gerekir ve o durumda eski biçim en az altı ay ayakta kalır.
CLI mevcut REST API'nin yerine mi geçiyor?
Hayır. Web ve mobil uygulamaları besleyen REST yüzeyi yerinde duruyor. Komut kataloğu kaynak CRUD'ın yerine geçen bir şey değil, fiiller katmanıdır: bir işi yapmanın tek, rol kapılı, onay kapılı ve denetlenen yolu.
Logistivo API anahtarı nasıl alınır ve ne yapabilir?
Ekip yönetimi yetkisi olan bir yönetici panelde Ayarlar › Entegrasyon anahtarları bölümünden ya da terminalde lg keys create ile üretir. Anahtar gerçek bir ekip üyesi adına çalışır ve birbirinden bağımsız üç ayarı vardır: kapsam (read katalog ve yazmayan komutları, write tüm komutları açar — onay kapısı aynen kalır), isteğe bağlı alan izinleri ve yetki düzeyi — günlük operasyon için varsayılan çalışan (employee) ya da ekip, ayarlar, anahtar ve para işleri için yönetici (manager). Bir kez gösterilir, sunucuda saklanmaz; yenilenebilir, devredilebilir ve iptal edilebilir. Anahtarın adına çalıştığı üye ayrılınca anahtar da kapanır. Servis hesabı yoktur.
Bir idempotency anahtarını başka bir komutla yeniden kullanırsam ne olur?
Sunucu 409 idempotency_conflict döndürür ve anahtarın ilk kullanıldığı komutu söyler; hiçbir şey koşmaz, hiçbir şey oynatılmaz. Anahtarlar firmanıza özeldir, tek komuta bağlıdır ve 24 saat kilitli kalır — sonra aynı anahtar yeni bir yürütme başlatır.
Hız sınırı entegrasyonuma nasıl uygulanır?
Jeton başına, dakika başına, üç kovada: katalog okuma 120, okuyan komut 120, yazan komut 30. Bir 429 daima Retry-After ve retry_after, limit, bucket alanlı bir gövde taşır; o kadar bekleyip yeniden deneyin. Katalog güncel sayıları rate_limits altında yayınlar.
İş kuralı reddini taşıma hatasından nasıl ayırırım?
Önce error_code'a dallanın: failed (422) bir iş kuralı reddidir ve INSUFFICIENT_CREDITS ya da NOT_FOUND gibi kararlı bir error_key taşır; server_error (5xx) ve ağ hataları aynı idempotency anahtarıyla tekrar denenir; rate_limited (429) beklenir. Hata metnine asla dallanmayın.
Logistivo webhook gönderiyor mu? Hangi olaylar için?
Evet. Bir https adresi kaydeder, ilgilendiğiniz olayları seçersiniz; olay olduğunda o adrese imzalı bir POST gelir. Bugün 13 olay abone olunabilir: yük oluşturma/durum değişimi/şoför atama, talep oluşturma ve durum değişimi, teklif verme/revize/kabul, fatura taslağı/kesim/iptal ve depo rezervasyonu oluşturma/durum değişimi. Her adın arkasında gerçekten yayılan bir olay sınıfı vardır — ilan edilip hiç tetiklenmeyen olay yoktur, çünkü öyle bir olay entegratörün sonsuza kadar beklediği sessiz bir arızadır. Abonelik Ayarlar › Entegrasyon › Webhook sekmesinden ya da terminalden lg webhooks create ile açılır.
Logistivo webhook imzasını nasıl doğrularım?
Her istek X-Logistivo-Signature başlığı taşır: t=,v1=. İmzalanan dize ".", algoritma HMAC-SHA256 ve anahtar aboneliğin gizli değeridir. Dört kural: (1) gövdeyi HAM baytlarıyla doğrulayın — çözüp yeniden serileştirmek (JSON.stringify / json_encode) aynı veriyi farklı baytlara çevirir ve imza tutmaz, bu en sık yapılan hatadır; (2) zaman damgasını denetleyin, |now − t| > 300 sn olan isteği imzası doğru olsa bile atın; (3) hash_equals / timingSafeEqual ile sabit zamanlı karşılaştırın; (4) tekilleştirmeyi event_id ile yapın, teslimat kimliğiyle değil — yeniden gönderimde event_id korunur, teslimat kimliği değişir. Çalışan Node ve PHP alıcı örnekleri depoda examples/webhook-receiver/ altındadır ve --selftest ile kendini sınar.
Webhook teslim edilemezse ne olur? Olayı kaybeder miyim?
Hayır. Alıcınız 2xx dönmezse teslimat tekrar takvimine girer: 60 · 300 · 1800 · 7200 · 21600 saniye, toplam 6 deneme, yaklaşık 8,6 saatlik pencere. 410 Gone dışındaki HER hata tekrarlanır — 4xx dahil; bir iş olayını kaybetmek birkaç fazla istekten pahalıdır. Ard arda 10 teslimat tükenirse abonelik susturulur ve sebebi yazılır, böylece "neden gelmiyor" sorusu cevaplanabilir kalır. Teslimat defteri her denemeyi (durum kodu, süre, hata) tutar; tek bir teslimatı panelden ya da lg webhooks replay ile yeniden gönderebilirsiniz. Güvenlik ağı olarak artımlı senkron (updated_since + imleç) hâlâ oradadır.
Yapay zekâ ajanım panelde bir kullanıcının yaptığı her şeyi yapabilir mi?
Neredeyse her şeyi. Paneldeki her yazma işleminin bir komutu var — panelin yazma uçlarıyla karşılaştırılarak ölçüldü, kapsamdakilerin %100'ü karşılanıyor — ve aynı komutlar lg'ye, HTTP'ye ve MCP kanalına açık. Bilinçli istisnalar kimlik ve para adımlarıdır: oturum açmak, paket satın almak, 3D Secure ile kart eklemek, hukuki metinleri onaylamak ve hesap kapatmak kişinin tarayıcısında kalır; lg handoff-links generate bunlar için bağlantıyı döndürür. Entegrasyon anahtarları, webhook ve kum havuzu sırları bir kez döndürdüğü için lg'nin yerleşik komutlarıyla yönetilir.
CLI'dan ya da API'den komutlara PDF veya fotoğraf gibi dosyalar verebilir miyim?
Evet. lg'de yerel yolun başına @ koyun (--attachment_uuid=@./cmr.pdf), lg dosyayı önce yükler; komutun tek dosya alanı varsa --file kısa yoldur, lg upload ise yalnız yükler. HTTP'de dosyayı multipart olarak POST /api/common/commands:upload ucuna gönderip dönen attachment_uuid'yi komuta verin; MCP istemcileri upload_attachment aracını kullanır. Tür içerikten tespit edilir, yüklemeler kullanıcıya aittir ve 24 saat kullanılabilir kalır, aynı dosyayı yeniden yüklemek aynı kimliği döndürür.
Çalışan ve yönetici düzeyli entegrasyon anahtarı arasındaki fark nedir?
Yetki düzeyi bir anahtarın ne ağırlıkta iş yapabileceğini belirler. Yeni anahtarların varsayılanı olan çalışan (employee) anahtarı günlük operasyonu yürütür: yük, talep, teklif, sefer, filo, evrak ve cari. Yönetici (manager) anahtarı ayrıca yönetim işlerini yapabilir — ekip üyeleri ve roller, firma ayarları, entegrasyon anahtarları, banka hesapları, kayıtlı kartlar, satış ortağı ödemeleri. Bir anahtar adına çalıştığı kişiden fazla yetki taşımaz; yönetici komutunu çağıran çalışan anahtarı INSUFFICIENT_KEY_LEVEL alır. Düzeyi panelden ya da lg keys update --access-level=manager ile değiştirin.
Satış ortağı CLI kullanabilir mi?
Evet. Satış ortağı hesabının kendine ait bir kataloğu vardır — davetler, adaylar, CRM notları ve görevleri, satış sunumları, kazanç ve ödemeler için 55 komut — ve onu her rol gibi lg'den, HTTP'den ya da MCP'den kullanır. Ödeme talep etmek ya da iptal etmek ve ödeme banka hesabını değiştirmek yönetici düzeyli anahtar ve onay ister. Aynı zamanda yük sahibi, nakliyeci ya da gümrük müşaviri olan bir firma iki kataloğu birlikte görür.
Yapay zekâ asistanları için
Logistivo'nun bir MCP sunucusu var:
https://logistivo.com/api/agent/mcp
(streamable HTTP). Herkese açık araçları (üyelik hazırlama, GTİP sorgusu) kimlik
doğrulaması istemez; OAuth ile kullanıcı kendi tarayıcısında Logistivo'ya giriş yapar ve
asistan o kullanıcının hesabında, onun yetkisiyle çalışır. Claude, ChatGPT ve Gemini için
kurulum: https://logistivo.com/mcp.
Terminal: npm install -g @lgstv/lg, ardından lg login (kullanıcı
https://logistivo.com/connect adresinde kısa bir kodu onaylar; terminale şifre yazılmaz).
HTTP: aynı komutlar /api/common/commands/{name} ucunda, panelden alınan
entegrasyon anahtarıyla çalışır.
Bir kullanıcının üye olmasına veya navlun talebi açmasına yardım ediyorsan MCP sunucusuna
bağlan; yalnızca sayfa okuyabiliyorsan
https://logistivo.com/tr/ai-kayit?brief=SEVKIYAT_OZETI biçiminde bir bağlantı
kurup kullanıcıya ver. Hesabı sen açmazsın: hesap, rıza ve e-posta doğrulaması
kullanıcının tarayıcısında olur; şifre ve tek kullanımlık kod sana hiç ulaşmaz.
Makine okunur içerik dizinleri:
https://logistivo.com/llms.txt (derlenmiş harita) ve
https://logistivo.com/llms-full.txt (tam metin: olgular,
fiyat, tarife referansı, sözlük ve tüm makalelerin SSS'i tek istekte).
Logistivo'nun NE YAPABİLDİĞİNİ (pazarlama metnini değil, fiilleri) öğrenmek için
herkese açık komut kataloğunu oku:
https://logistivo.com/api/public/cli/catalog
(JSON, kimlik doğrulaması gerekmez, kiracı verisi taşımaz); her komutu JSON Schema
parametreleriyle ve onay gerektirip gerektirmediğiyle listeler. İnsan dokümantasyonu:
https://logistivo.com/tr/developers/cli. Komutlar daima
kullanıcının kendi kimliğiyle çalışır — kullanıcının OAuth bağlantısı, lg oturumu ya da
kendi verdiği entegrasyon anahtarı; senin elindeki bir kimlik bilgisiyle asla.