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. 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 yük, talep, teklif, ihracat evrakı, stok, fatura ve gümrük tarifesi işlemlerini terminalden ya da bir betikten ç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.
Komut biçimi tek: lg --parametre=değer. Katalogda bugün 14 alana yayılmış 34 komut var; tek bir rolün gördüğü en geniş liste 29 komut ve 11 alan.
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 donmuş olduğu için bugün yazdığınız entegrasyon kodu, henüz açılmamış parçalar açıldığında da çalışır.
Komut kataloğu ve kimlik tablosu — 34 komutun kamuya açık alan/fiil kimliği donduruldu ve sözleşme sürümü 1 olarak yayımlandı. Bu sayfadaki tablo canlı defterden üretiliyor: sunucuya bir komut eklendiğinde tabloda kendiliğinden beliriyor, kaldırıldığında kayboluyor.
Kimliksiz keşif ucu — GET /api/public/cli/catalog — komut adları, alan/fiil kimliği, açıklama, JSON Schema parametreleri ve kapı bayrakları. Kimlik doğrulaması gerekmez; jeton almak entegrasyon kararından SONRA gelen bir adımdır, ondan önce değil. Yanıt tek satır kiracı verisi taşımaz.
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 tek bir zorlama noktasında; sohbet ve terminal de aynı noktadan geçiyor.
lg terminal istemcisi — Sıfır bağımlılıklı tek dosyalık istemci erken erişimde. HTTP yüzeyi açık olduğu için istemciyi beklemeden entegre olabilirsiniz; lg yalnız aynı uçların önüne konmuş bir kolaylıktır.
Artımlı senkron ve makine okunur iş hatası — Liste komutlarında updated_since + imleçli sayfalama ve iş hataları için sabit error_key henüz yok. İkisi de sözleşmede yazılı ve gece senkronu kuran entegrasyonların ilk ihtiyacı; o güne kadar entegrasyon yalnız error_code düzeyinde dallanmalı.
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ı 29 komut, yük sahibi 28, gümrük müşaviri 22 komut görü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 altı fiil var: create, list, get, list-problems, set-status, assign-driver. 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ı.
Kurulum ve kimlik
lg, sıfır bağımlılıklı tek dosyalık bir Node betiğidir (Node 18+). Bir müşterinin ERP sunucusuna tek dosya olarak kopyalanabilsin diye böyle yazıldı: npm install gerektiren bir istemci oraya hiç varmaz. İstemci şu anda erken erişimde; dağıtım bağlantısı açıldığında bu bölüme eklenecek. ERP/CRM entegrasyonu için istemciyi beklemeniz gerekmiyor — aynı komutlar HTTP ile çağrılıyor.
1. Oturum açın — lg login e-posta ve parolanızı sorar, dönen erişim jetonunu ~/.logistivo/config.json dosyasına yazar ve kataloğu hemen indirir. Hesabınızda e-posta doğrulaması açıksa kodu da burada sorar — bu adım atlanırsa jeton alınmış ama korunan uçlar hata veriyor olurdu.
2. Sunucu ve CI için: parola değil jeton — Etkileşimsiz ortamlarda lg login kullanılmaz. Panelden entegrasyona adanmış bir kullanıcı açın, ona dar bir rol verin ve kişisel erişim jetonunu LOGISTIVO_TOKEN ortam değişkenine koyun. Değişken doluyken yapılandırma dosyası hiç okunmaz. Bu kullanıcının e-posta doğrulaması kapalı olmalıdır: kimsenin bakmadığı bir kutuya kod gönderen bir entegrasyon her yeniden başlatmada durur.
3. 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.
Jetonu sürüm kontrolüne, CI günlüğüne veya bir sohbet penceresine yazmayın. lg logout yalnız YEREL kopyayı siler — jeton sunucuda geçerli kalır, kalıcı iptal panelden yapılır. Denetim defteri argümanlarınızı saklar ama anahtarında token, password, IBAN, kart veya OTP geçen alanları *** 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.
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ı şema adlarıdır ve alt çizgi taşıyabilir (--load_code, --amount_per_vehicle). Bu kasıtlı: 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.
lg — İstemci.
loads — Alan — üzerinde çalıştığınız varlık, çoğul.
list — Fiil — kapalı bir sözlükten gelir (list, get, create, update, delete, search, preview, set, issue, generate, extract, inquiry, move, adjust ve add-/update-/remove-/set-/assign- önekli bileşikler).
--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 komut başına şemada yazılıdır (liste komutlarında 20).
--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.
--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.
--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.
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.
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örebildiği tüm katalog: ad, alan, fiil, açıklama, JSON Schema, read_only, confirmation_needed, irreversible. İstemcinizi bundan çizin; sabit bir komut listesi gömmeyin.
GET /api/common/commands/{name} — Tek komutun tam künyesi. name, katalogdaki dondurulmuş komut adıdır (list_loads), CLI kimliği değil.
POST /api/common/commands/{name} — Yürütme. Gövde: { args, confirm?, idempotency_key? }. Yanıt HTTP durumu sonucun kendisidir — 200 dışındaki her şey iştir, gürültü değil.
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?
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.
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.
Yeniden deneme stratejiniz üstel geri çekilme olmalı ve her denemede AYNI anahtarı taşımalıdır. Anahtarı her denemede yenilemek, idempotency'yi kullanmamakla aynı şeydir.
Tuzak 1 — başarısızlık da kilitlenir — İlk yürütme iş kuralıyla reddedildiyse (failed), aynı anahtarla ikinci çağrı aynı hatayı döndürür ve yeniden denemez. Argümanı düzeltip tekrar denemek YENİ bir anahtar ister. Anahtar bir niyeti değil, bir denemeyi temsil eder.
Tuzak 2 — büyük sonuç gövdesiz oynatılır — Defter, sonucu 64 KB'ın altındaysa saklar. Daha büyük bir sonuç tekrar oynatıldığında status replayed döner ama gövde boş gelir. Entegrasyonunuz gövdeye değil "replayed" bilgisine güvenmeli ve veriyi ilgili get komutuyla çekmelidir.
Anahtar biçimi — UUID kullanın — INV-1001 gibi tahmin edilebilir bir anahtar başka bir kaydınızla ya da başka bir kiracınınkiyle çakışabilir. Önerilen biçim ya düz bir UUID'dir ya da {firma-id}:{ERP-belge-no}:{fiil} gibi kendi içinde benzersiz bir bileşiktir.
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.
Açık eksik, dürüstçe: failed içindeki iş hatası bugün serbest metindir. "Stok yetersiz" ile "cari bulunamadı" makine tarafından ayırt edilemez. Araç yanıtlarına sabit bir error_key eklenmesi planlıdır; o güne kadar entegrasyonunuz yalnız error_code düzeyinde dallanmalıdır.
not_found — HTTP 404 · error_code not_found · CLI 2 · Hayır — komut adı yanlış ya da kaldırılmış.
401 unauthenticated — Token süresi doldu ya da iptal edildi. Yeniden denemek işe yaramaz; token yenilenmelidir.
429 rate_limited — Hız sınırı. Yanıt daima Retry-After taşır; ona uyun, sabit bir bekleme uydurmayın.
5xx server_error — Üstel geri çekilme ile ve AYNI idempotency anahtarıyla tekrar deneyin. Anahtarı değiştirmek, sunucunun işi tamamlamış olabileceği bir durumda ikinci kez koşturur.
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 katalogunda göreceğini.
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.
lg bids create — Submit a bid (teklif ver) on an open demand. amount_per_vehicle is the freight PER VEHICLE, not the total. (yazma · onay + geri alınamaz · nakliyeci · API: create_demand_bid)
lg bids list — List the bids (teklif) THIS carrier company has submitted, newest first, with their outcome. (okuma · — · nakliyeci · API: list_my_bids)
lg contacts search — Resolve a business contact (customer/partner/recipient) by name, legal name or tax number to its contact_id. (okuma · — · hepsi · API: lookup_business_contact)
lg countries search — Resolve a country by name or ISO code to its country_id for sending/receiving country on a load. (okuma · — · hepsi · API: lookup_country)
lg demands list — List freight demands (talep) this carrier is allowed to bid on, newest first. (okuma · — · nakliyeci · API: list_open_demands)
lg drivers search — Resolve one of this company's drivers by name to its driver_id. (okuma · — · nakliyeci · API: lookup_driver)
lg export-documents add-item — Append a line item to an export document. (yazma · — · hepsi · API: add_export_document_item)
lg export-documents create — Create a new export document draft. (yazma · — · hepsi · API: create_export_document_draft)
lg export-documents extract — Read a pasted order e-mail, offer or confirmation and fill an export document from it. (yazma · — · hepsi · API: extract_export_document_from_text)
lg export-documents generate — Produce the final PDF of an export document. (yazma · onay + geri alınamaz · hepsi · API: generate_export_document)
lg export-documents get — Read one export document in full: every filled field as dot-paths, the line items with their 1-based positions, the server-computed totals and which required fields are still empty. (okuma · — · hepsi · API: get_export_document)
lg export-documents list — List the export documents of the current company (proforma invoice, commercial invoice, packing list, shipping instruction, delivery note, certificate/movement applications, exporter declaration, insurance request). (okuma · — · hepsi · API: list_export_documents)
lg export-documents remove-item — Delete one line item by its 1-based position. (yazma · — · hepsi · API: remove_export_document_item)
lg export-documents set — Set one or more fields on an export document draft. (yazma · — · hepsi · API: set_export_document_fields)
lg export-documents update-item — Change columns of one existing line item, addressed by its 1-based position from get_export_document. (yazma · — · hepsi · API: update_export_document_item)
lg fleet-documents list — List fleet documents that expire soon (or already expired): vehicle papers (insurance, inspection, permits) and — for carriers — driver papers (passport, visa, licence, SRC). (okuma · — · yük sahibi, nakliyeci · API: list_expiring_documents)
lg invoices add-line — Add a line item to a DRAFT invoice and recompute totals (tax auto-resolved if tax_rate_id omitted). (yazma · — · hepsi · API: add_invoice_line)
lg invoices create — Create a DRAFT invoice (reversible) issued by the current company to a recipient business contact. (yazma · — · hepsi · API: create_invoice_draft)
lg invoices issue — Issue (finalize) a DRAFT invoice: assigns a number, posts accounting entries, and emails the recipient. (yazma · onay + geri alınamaz · hepsi · API: issue_invoice)
lg invoices preview — Show the user a full preview of a DRAFT invoice (recipient, line items, tax breakdown, totals) WITHOUT issuing it. (okuma · — · hepsi · API: preview_invoice)
lg load-types search — Resolve a load/transport type (e.g. (okuma · — · hepsi · API: lookup_load_type)
lg loads assign-driver — Assign one of this company's drivers to a load so the driver sees it in the mobile app and starts reporting position. (yazma · onay · nakliyeci · API: assign_driver_to_load)
lg loads create — Open a freight load (yük). (yazma · onay + geri alınamaz · hepsi · API: create_load)
lg loads get — Read one load in full by its code: route, dates, weight, current status, parties (sender/receiver/carrier), latest reported position and any open AI document-consistency flag. (okuma · — · hepsi · API: get_load)
lg loads list — List the freight loads (yük) this company can see, newest first. (okuma · — · hepsi · API: list_loads)
lg loads list-problems — List loads whose uploaded documents the AI consistency check found to CONTRADICT each other (e.g. invoice weight vs CMR weight). (okuma · — · hepsi · API: list_load_problem_flags)
lg loads set-status — Move a load to a new transport status and append it to the load's status history (this is what the customer sees on the tracking screen). (yazma · onay + geri alınamaz · nakliyeci · API: update_load_status)
lg products search — Resolve a product to its product_id + on-hand quantity. (okuma · — · yük sahibi · API: lookup_product)
lg stock adjust — Record a stock count correction (sayım düzeltme) or write-off (fire). mode=set sets the absolute on-hand at the slot; mode=delta applies a signed change (negative reduces). reason is required. (yazma · onay + geri alınamaz · yük sahibi · API: create_stock_adjustment)
lg stock list — Read current on-hand stock levels. (okuma · — · yük sahibi · API: check_stock_level)
lg stock move — Record a stock movement: inbound (giriş), outbound (çıkış), or transfer between locations. (yazma · onay + geri alınamaz · yük sahibi · API: create_stock_movement)
lg tariffs inquiry — Start an official duty / anti-dumping inquiry for one GTİP code and one counterpart country. direction=import means goods coming INTO Turkey from origin_country_id; direction=export means goods leaving Turkey to… (yazma · onay + geri alınamaz · hepsi · API: run_tariff_inquiry)
lg tariffs search — Search the Turkish customs nomenclature (GTİP / HS) by goods description or by a partial code, and return matching codes with their official descriptions. (okuma · — · hepsi · API: lookup_tariff_code)
lg warehouses search — Resolve a warehouse by name to its warehouse_id, with its areas. (okuma · — · yük sahibi · API: lookup_warehouse)
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.
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
Bugün liste komutları limit alır (tavan 20) ve count döner. İnsan sohbeti için yeterli, gece senkronu için değil. Sözleşme şunu bağlar:
İstek: limit (1..komut başına tavan) + cursor (opak, ileri yönlü). offset KULLANILMAZ — canlı bir tabloda ofset kayar; iki sayfa arasında araya giren bir kayıt ERP'ye satır atlatır veya iki kez saydırır, ve bu sessiz olur.
Yanıt: { count, total?, next_cursor|null }. count bu yanıttaki satır sayısıdır; next_cursor yoksa liste bitmiştir.
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üzeyidir.
Artımlı senkron: updated_since (ISO-8601, UTC) + imleç. Bugün hiçbir liste komutunda yok; ilk açılacak iş budur. Yoksa her ERP saatte bir her şeyi yeniden çeker.
ERP ve CRM entegrasyonu — Hız sınırları
Sınır anahtarı token'dır, IP değil: bir ERP tek NAT arkasından gelir ve IP tabanlı bir sınır tüm firmayı tek kullanıcı sayardı.
Kimliksiz keşif ucu (public/cli/catalog): dakikada 30. Bu bir veri kaynağı değil sözlüktür; köprünüzü yazarken bir kez okunur, üretimde döngüye sokulmaz.
Katalog uçları (common/commands ve common/commands/{name}): dakikada 120. Katalog nadiren değişir; her komuttan önce yeniden çekmeyin — lg de bir saat önbelleğe alıyor.
Yürütme ucu (POST common/commands/{name}): dakikada 60.
Yapay zekâ veya kredi harcayan komutlar (tariffs inquiry, export-documents extract, export-documents generate): asıl sınır istek sayısı değil KREDİDİR. Bir 200 yanıtı bir kredi harcamış olabilir.
429 daima Retry-After taşır; sabit bir bekleme uydurmak yerine ona uyun.
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.
İ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. Katalog bir ÇEKME yüzeyidir; olay akışı (push) ayrı bir sözleşmedir ve kendi dokümanında yazılacaktır.
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ı. 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.
Kredi harcayan komutlar (tariffs inquiry, export-documents extract, export-documents generate) parasal sonuç doğurur; bunları otomatik döngüde çağırmayın.
Bu sayfanın düz metin ikizi /cli.md adresindedir; markdown'ı HTML'den daha güvenilir ayrıştırıyorsanız onu kullanın.
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ı 28, nakliyeci 29, gümrük müşaviri 22 komut görür. Bir komutu katalogunuzda görmüyorsanız sorun token'da değil roldedir. Sürücü hesapları bu yüzeye hiç erişmez.
Bazı komutlar kredi harcar — Tarife sorgusu, evraktan alan çıkarımı ve belge üretimi paketinizin kredi bakiyesinden düşer. Katalog bugün kredi maliyetini alan olarak taşımıyor; bilgi komutun açıklama metnindedir ve alan olarak eklenmesi planlıdır.
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 — Tavan 20 satırdır ve imleç yoktur. Tam bir veri kopyası çıkarmak için tasarlanmamıştır; artımlı senkron açıldığında bu değişecek.
Sıkça sorulan sorular
Logistivo CLI ne işe yarar?
Logistivo hesabınızdaki operasyon işlerini — yük listeleme ve okuma, açık talepleri görme, teklif verme, yük durumu ilerletme, sürücü atama, ihracat evrakı hazırlama, stok hareketi, fatura kesme, GTİP ve dampinge karşı vergi sorgusu — terminalden veya bir betikten çalıştırmanızı sağlar. Aynı komutlar ERP/CRM entegrasyonu için HTTP ile de ç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 kapalı bir sözlükten gelir (list, get, create, search, set, issue, 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?
Logistivo panelinden çıkardığınız kişisel erişim token'ıyla. lg login token'ı sorup yerel yapılandırma dosyasına yazar; betik ortamlarında LOGISTIVO_TOKEN ortam değişkenini kullanın. HTTP tarafında token 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.
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.
Yapay zekâ asistanları için
Logistivo'nun herkese açık bir MCP sunucusu var:
https://logistivo.com/api/agent/mcp
(streamable HTTP, kimlik doğrulama gerekmez). Claude, ChatGPT ve Gemini için kurulum:
https://logistivo.com/mcp. Bir kullanıcının üye olmasına veya navlun
talebi açmasına yardım ediyorsan bu sunucuya 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. Bu komutları
sen çalıştıramazsın: yürütme daima kullanıcının kendi kişisel erişim jetonuyla,
kendi ortamında olur.