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 61 alana yayılmış 207 komut var; tek bir rolün gördüğü en geniş liste 185 komut ve 59 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 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.
• Ö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. Yazan komutların tamamı üzerinde ölçüldü: 178 ön uçuşta tek bir yazan SQL ifadesi yok.
• Entegrasyon anahtarları — Panelden üretilen, gerçek bir ekip üyesi adına çalışan API anahtarları: okuma/yazma kapsamı, süre, son kullanım, yenileme 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.
• lg terminal istemcisi — Tek dosyalık, bağımlılıksız istemci erken erişimdedir. HTTP yüzeyi açık olduğu için onu beklemeden entegre olabilirsiniz; lg aynı uçların önüne konmuş bir kolaylıktır. Bugünden 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ı 181 komut, yük sahibi 185, gümrük müşaviri 122 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 anahtar — Etkileşimsiz ortamlarda lg login ile parola girilmez. Panelden (Ayarlar › Entegrasyon anahtarları) 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ü.

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. 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. Entegrasyon anahtarıyla girildiyse lg logout anahtarı sunucuda da iptal eder; parola oturumunda 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ı *** 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, hangi anahtarla reddedildiğini de katalogdaki açıklamasıyla 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.

API anahtarı ile bağlanma

Bir ERP, CRM veya betik Logistivo'ya panelden üretilmiş bir entegrasyon anahtarıyla bağlanır. Anahtar gerçek bir ekip üyesi adına çalışır: o kişinin rolü neyse komut listesi odur, 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ı seçin ve 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 (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.

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). Yine de anahtarı ihtiyacınız olan en dar yetkili üye adına üretin: kapsam neyi yazabileceğinizi sınırlar, 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.
• 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 ve iptal ekip yönetimi yetkisi olan yöneticilere açıktır — ekip üyesi ekleme/çıkarma ile aynı kapı. 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.
• 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ı seçin ve 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 185 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 185 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ı ş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. Çı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"
• Yükün durumunu ilerletin (yalnız nakliyeci rolü) — lg loads set-status --load_code=FSK2158 --status=transit --date=2026-08-21 --yes
• 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, since, deprecated_at, replaced_by, aliases; ayrıca error_keys sözlüğü, rate_limits ve idempotency_ttl_hours. 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.

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.

Ö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 207 komut var; 105 tanesi okuma yapar ve bir şey yazmaz. Geriye kalan 102 yazan komuttan 85 tanesi onay kapılıdır: confirm olmadan çağrıldıklarında zaten 409 ile ne yapacaklarını anlatırlar. Sorun kalan 17 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 vaat değil, ölçüm: 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.
• limit — Sayfa boyu. Senkron kipinde 1-100 (varsayılan 10).
• 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.

• ok — HTTP 200 · error_code — · CLI 0 · —
• replayed — HTTP 200 · error_code — · CLI 0 · Idempotent tekrar; iş YENİDEN KOŞMADI.
• failed — HTTP 422 · error_code failed · CLI 1 · Hayır — iş kuralı reddetti (error_key'e bakın). Argüman değişmeden anlamsız.
• needs_confirmation — HTTP 409 · error_code needs_confirmation · CLI 4 · Evet, confirm: true ile.
• 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.
• server_error — HTTP 500 · error_code server_error · CLI 6 · Evet — AYNI idempotency anahtarıyla üstel geri çekilme; anahtar kilitlenmedi.
• 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 network_error ya da server_error koduyla 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 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 accounting-settings get — Read the company's accounting and invoicing settings and say whether they are set up (muhasebe ayarları, fatura ayarları, e-fatura / e-invoice profile, KDV / VAT tax regime, fatura numaralandırma serisi / invoice… (okuma · — · hepsi · API: get_accounting_settings)
• lg accounting-settings update — Update the company's accounting/invoicing settings (muhasebe ve fatura ayarlarını değiştir): legal name, default currency, provider (local/parasut), country, tax regime (KDV/VAT/GST/none), default invoice line… (yazma · onay · hepsi · API: update_accounting_settings)
• lg attachments get — Read a file the user attached to THIS conversation (listed in the user message as [Attachments] with their attachment_uuid). (okuma · — · hepsi · API: read_attachment)
• lg bank-accounts create — Add one of YOUR OWN company bank accounts to the account book (the accounts you get paid into). (yazma · onay · hepsi · API: create_company_bank_account)
• lg bank-accounts list — List bank accounts. (okuma · — · hepsi · API: list_bank_accounts)
• lg bank-accounts set-status — Confirm or reject a bank account that was read from a document by AI. (yazma · onay · hepsi · API: decide_bank_account_verification)
• lg bids accept — Accept a carrier's bid on one of this company's demands. (yazma · onay + geri alınamaz · yük sahibi · API: accept_demand_bid)
• lg bids create — Submit a bid (teklif ver) on an open demand. amount_per_vehicle is the freight PER VEHICLE, not the total. (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 bids revise — Revise this carrier's own PENDING bid on a demand: the old bid is marked revised and a NEW bid replaces it (it gets a new bid code). (yazma · onay + geri alınamaz · nakliyeci · API: revise_demand_bid)
• lg carbon-reports calculate — Calculate the CO2 emission of an EXISTING load from its own data: the weight on the load, the route between its first pickup and last delivery address (including the Ro-Ro leg when the load has one), the distance, the… (okuma · — · hepsi · API: calculate_load_carbon_emission)
• lg carbon-reports get — Read one CO2 emission report in full: total emission in kg, transport mode, weight, distance, emission factor, calculation method and source, the departure/arrival addresses, the leg breakdown for multi-modal routes… (okuma · — · hepsi · API: get_carbon_emission_report)
• lg carbon-reports list — List the CO2 emission reports this company has generated (newest first): report number, file name, who created it and when. (okuma · — · hepsi · API: list_carbon_emission_reports)
• lg chart-of-accounts list — List the chart of accounts available to this company (Turkish uniform chart: 100 Kasa, 102 Bankalar, 120 Alıcılar, 320 Satıcılar, 391 Hesaplanan KDV, 600/601 Satışlar…), optionally filtered by code/name text or type. (okuma · — · hepsi · API: list_chart_of_accounts)
• lg checks bounce — Record that a cheque BOUNCED (came back unpaid). (yazma · onay + geri alınamaz · hepsi · API: mark_check_bounced)
• lg checks collect — Record that a cheque was COLLECTED (money reached the bank for an incoming cheque, or left the bank for an outgoing one) on its due date. (yazma · onay + geri alınamaz · hepsi · API: mark_check_collected)
• lg checks get — Read one cheque in full: its identity (number, serial, bank and branch, drawer with tax number, IBAN), the face amount and currency, issue and due dates, the counterparty, the status with every timestamp (executed,… (okuma · — · hepsi · API: get_settlement_check)
• lg checks list — List the cheque portfolio of this company: cheque number, direction (in = received from a customer, out = given to a supplier), drawer and bank, face amount with its currency, issue and DUE date, the counterparty… (okuma · — · hepsi · API: list_settlement_checks)
• lg company-documents list — List this company's own filed documents (tax certificate, signature circulars, trade registry gazette, contracts, TIO/L2 permits, files uploaded to chats…) with their type, number, validity date and verification status. (okuma · — · hepsi · API: list_company_documents)
• lg contacts add-bank-account — Add a bank account (IBAN) to a business contact so it can be used on payment instructions and invoices. (yazma · onay · hepsi · API: add_business_contact_bank_account)
• lg contacts create — Create a new business contact (cari) in the company directory. (yazma · onay · hepsi · API: create_business_contact)
• lg contacts get — Read one business contact in full (identity, tax data, address, e-mail/phone, bank accounts, platform link) together with its account summary: ledger balance (positive = they owe us), open receivables and open payables. (okuma · — · hepsi · API: get_business_contact)
• lg contacts list — List the company's business contacts (customers, carriers, suppliers, consignees) with optional text search over name, legal name and tax number. (okuma · — · hepsi · API: list_business_contacts)
• 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 contacts update — Update fields of an existing business contact. (yazma · onay · hepsi · API: update_business_contact)
• lg conversations add-message — Post a message into a load/bid conversation AS THIS USER (not as an assistant). (yazma · onay + geri alınamaz · hepsi · API: send_conversation_message)
• lg conversations list — List the chat conversations this user is a member of (load chats, bid chats and private carrier channels), newest activity first. (okuma · — · hepsi · API: list_conversations)
• lg conversations list-messages — Read the most recent messages of one conversation — give it a load code (e.g. (okuma · — · hepsi · API: list_conversation_messages)
• lg conversations list-participants — Who is in this conversation — name and company of every participant. (okuma · — · hepsi · API: list_conversation_participants)
• lg conversations mark-read — Mark one conversation as read for this user (clears its unread badge). (yazma · — · hepsi · API: mark_conversation_read)
• lg conversations remove-message — Delete one of THIS user's own messages from a conversation (message_id from list_conversation_messages with `mine` true). (yazma · onay + geri alınamaz · hepsi · API: delete_conversation_message)
• lg conversations update-message — Edit one of THIS user's own messages in a conversation (message_id comes from list_conversation_messages, where `mine` is true). (yazma · onay · hepsi · API: update_conversation_message)
• lg countries search — Resolve a country by name (Turkish, English or the local/native name) or ISO 3166-1 alpha-2 code to its country_id, for the sending/receiving country on a load. (okuma · — · hepsi · API: lookup_country)
• lg demand-targets search — Resolve a pickup/delivery location for a demand to a target token ("5-" = district/postal area, "10-" = seaport address). (okuma · — · yük sahibi · API: lookup_demand_target)
• lg demands create — Open a freight demand (talep) so carriers can bid. (yazma · onay + geri alınamaz · yük sahibi · API: create_demand)
• lg demands get — Detail of ONE demand owned by this customer company, INCLUDING the bids it received (bid_code, carrier name — masked as an alias when the carrier chose to stay hidden — price per vehicle, total, currency, vehicle count,… (okuma · — · yük sahibi · API: get_demand)
• lg demands list — List freight demands (talep) this carrier is allowed to bid on, newest first. (okuma · — · nakliyeci · API: list_open_demands)
• lg demands list-own — List the freight demands (talep) OWNED by this customer company, newest first, with route, dates, vehicles, status and bid count. (okuma · — · yük sahibi · API: list_demands)
• lg demands options — Reference lists needed to build a freight demand (talep) with create_demand: vehicle types (id, name, transport mode), payment maturity options (id + days; company_default_maturity_option_id is what the company normally… (okuma · — · yük sahibi · API: get_demand_form_options)
• lg demands set-status — Close (make passive) one of this company's ACTIVE demands so carriers stop bidding. (yazma · onay + geri alınamaz · yük sahibi · API: close_demand)
• lg document-checks run — Cross-check documents the user attached to THIS conversation against each other and report the discrepancies: mismatched party names, quantities, weights, amounts, dates, container or reference numbers between an… (yazma · — · hepsi · API: check_document_compliance)
• lg documents download — Get a short-lived (15 minute) download/preview link for one document by its document_id (from list_load_documents or list_company_documents). (okuma · — · hepsi · API: get_document_link)
• lg driver-accounts get — Answer "how much do we owe this driver / how much does the driver owe us". (okuma · — · yük sahibi, nakliyeci · API: get_driver_account_summary)
• lg driver-advances create — Record a money movement between the company and a driver: an advance handed to the driver, money the driver gave back, a closing payout, or a carry-forward opening balance. (yazma · onay · yük sahibi, nakliyeci · API: create_driver_advance)
• lg driver-advances list — List the money movements between the company and its drivers: cash advances handed out, money paid back by the driver, closing payouts and carry-forward opening balances. (okuma · — · yük sahibi, nakliyeci · API: list_driver_advances)
• lg driver-expenses create — File one or MANY expense receipts the user attached to this conversation (fuel, toll, ferry, parking, repair, meal…) into the driver expense ledger as pending expenses of ONE of this company's drivers. (yazma · onay + geri alınamaz · yük sahibi, nakliyeci · API: process_receipt)
• lg driver-expenses get — Read one driver expense (receipt) by its id: merchant, amount, currency, converted amount, category, payment channel, whether it is charged to the driver, and the approval status. (okuma · — · yük sahibi, nakliyeci · API: get_driver_expense)
• lg driver-expenses list — List driver expense receipts (fuel, toll, ferry, parking, food, repair…) with a converted total. (okuma · — · yük sahibi, nakliyeci · API: list_driver_expenses)
• lg driver-expenses review — Approve or reject ONE driver expense (receipt) from the chat, or send an already-decided one back to pending. status=approved means the company accepts the expense (an approved reimbursable receipt can then be counted… (yazma · onay · yük sahibi, nakliyeci · API: review_driver_expense)
• lg driver-statements cancel — Cancel a statement that should not exist (opened by mistake, duplicated). (yazma · onay + geri alınamaz · yük sahibi, nakliyeci · API: cancel_driver_account)
• lg driver-statements create — Open a NEW draft settlement statement for a driver. (yazma · onay · yük sahibi, nakliyeci · API: create_driver_account)
• lg driver-statements finalize — FINALISE a draft settlement statement — it freezes the document, makes it visible to the driver and (for settle_cash) writes the counter-entry into the advance ledger. (yazma · onay + geri alınamaz · yük sahibi, nakliyeci · API: finalize_driver_account)
• lg driver-statements get — Read one driver settlement statement in full: its status and revision, the driver, the currency, every total (expenses, advances, repayments, receiptless declarations), the NET balance with the sentence that says which… (okuma · — · yük sahibi, nakliyeci · API: get_driver_account)
• lg driver-statements list — List the driver settlement statements (mutabakat belgesi) of this company: code, which driver, status (draft / finalized / cancelled), currency, the net balance and what it means, how many expense and advance lines it… (okuma · — · yük sahibi, nakliyeci · API: list_driver_accounts)
• lg driver-statements reopen — Reopen a FINALISED statement so it can be corrected (a late receipt arrived, a line was wrong). (yazma · onay · yük sahibi, nakliyeci · API: reopen_driver_account)
• lg driver-statements update-lines — Attach receipts/advances to a DRAFT statement, or detach ones that should not be on it. (yazma · onay · yük sahibi, nakliyeci · API: update_driver_account_lines)
• lg drivers add-document — Record a driver paper — visa, passport, residence permit, driving licence, SRC certificate, psychotechnic certificate, travel health insurance — for ONE of this carrier's drivers, so its expiry is tracked. (yazma · onay · nakliyeci · API: add_driver_document)
• lg drivers archive — Archive (deactivate) a driver: their account is disabled, open mobile sessions are revoked and the login link stops working. (yazma · onay + geri alınamaz · nakliyeci · API: archive_driver)
• lg drivers create — Create a new driver account for this carrier company. (yazma · onay · nakliyeci · API: create_driver)
• lg drivers delete-document — Remove a driver paper from the driver's file. (yazma · onay + geri alınamaz · nakliyeci · API: delete_driver_document)
• lg drivers get — Full detail of ONE driver of this carrier: identity, archive state, mobile app state, last GPS position, assigned load codes, ALL driver documents (passport, visa, licence, SRC… with expiry and days_to_expiry) and the… (okuma · — · nakliyeci · API: get_driver)
• lg drivers list — List this carrier company's drivers with their status, current country, expiring/expired document counts, assigned load codes and vehicle plates. (okuma · — · nakliyeci · API: list_drivers)
• lg drivers list-documents — List ONE driver's documents (passport, visa, residence permit, licence, SRC, ADR, health insurance…) with document number, issuing country, valid_until, days_to_expiry, is_expired and AI extraction status. (okuma · — · nakliyeci · API: list_driver_documents)
• lg drivers login-link — Produce the driver's 48-hour mobile app login link (sensitive credential). (yazma · onay · nakliyeci · API: get_driver_login_link)
• lg drivers search — Resolve one of this company's drivers by name to its driver_id. (okuma · — · nakliyeci · API: lookup_driver)
• lg drivers update — Correct a driver's first/last name. (yazma · onay · nakliyeci · API: update_driver)
• lg drivers update-document — Correct a driver paper already on file — most often its expiry date (valid_until) after a renewal, but also the document number, the issuing country, the type or the note. (yazma · onay · nakliyeci · API: update_driver_document)
• lg equipment-damages list — List the equipment/trailer damages recorded for this company: which vehicle, where on it (area and angle), damage type and severity, whether it is still open or repaired, the estimated and actual repair cost, who is… (okuma · — · hepsi · API: list_equipment_damages)
• lg equipment-inspections list — List the equipment hand-over inspections (teslim-tesellüm controls) of this company: which vehicle, the event type (hand-over, take-over, interim), when and where it happened, who performed it (driver or office user, or… (okuma · — · hepsi · API: list_equipment_inspections)
• 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 AND return a short-lived signed download link for it, so the user gets the file straight from the chat. (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 finance get — One call that returns the measured financial BASE for a period — the numbers a budget, a forecast, a business plan, a cash-flow projection or a board summary is built on, instead of chaining six separate reads. (okuma · — · hepsi · API: get_financial_snapshot)
• lg fleet-documents list — List fleet documents that expire soon (or already expired): vehicle papers (insurance, inspection, permits) and — for carriers — driver papers (passport, visa, licence, SRC). (okuma · — · yük sahibi, nakliyeci · API: list_expiring_documents)
• lg fuel-cards create — Register a fuel card (DKV, UTA and the like) in the fleet card book, optionally tied to a driver or a vehicle. (yazma · onay · yük sahibi, nakliyeci · API: create_fuel_card)
• lg fuel-cards list — List the company's fuel and toll cards (DKV, UTA, Eurowag, E100, Shell, OMV, Aral, Petrol Ofisi, Opet…) with the last four digits, the driver or vehicle they are tied to, and whether they are active. (okuma · — · yük sahibi, nakliyeci · API: list_fuel_cards)
• lg fuel-cards update — Update a fuel card: move it to another driver or vehicle, change its label or note, or DEACTIVATE it (is_active false) when the card is cancelled. (yazma · onay · yük sahibi, nakliyeci · API: update_fuel_card)
• lg import-duties get — Read the Turkish import duty table for one GTİP code: customs duty (İthalat Rejimi Kararı) and additional customs duty / İGV, with every country-group column, plus the statutory duty from the nomenclature. (okuma · — · hepsi · API: get_import_duty_rates)
• lg invitations create — Invite a colleague to this company by e-mail. (yazma · onay + geri alınamaz · hepsi · API: invite_teammate)
• lg invitations list — List teammate invitations of this company that are not completed yet (pending / e-mail verified / account created), with invitation_code, e-mail, role and expiry. (okuma · — · hepsi · API: list_pending_invitations)
• lg invitations resend — Re-send a pending teammate invitation e-mail and extend its expiry by 14 days. (yazma · onay + geri alınamaz · hepsi · API: resend_invitation)
• lg invitations revoke — Cancel a pending teammate invitation so its link stops working (it can later be re-sent). (yazma · onay · hepsi · API: revoke_invitation)
• lg invoice-settings get — Read the invoice document settings (fatura ayarları, fatura şablonu ayarları): which invoice templates exist, which template configuration is the company default, which fields of it are filled (logo, seller address,… (okuma · — · hepsi · API: get_invoice_settings)
• 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 add-payment — Record money received (sales invoice) or paid (purchase invoice) against ONE issued invoice: writes the payment, posts the balanced journal entry and reduces the remaining balance. (yazma · onay + geri alınamaz · hepsi · API: record_invoice_payment)
• lg invoices cancel — Cancel an ISSUED invoice this company issued: posts the reversing journal entry and marks the invoice cancelled. (yazma · onay + geri alınamaz · hepsi · API: cancel_invoice)
• 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 delete-draft — Delete a DRAFT invoice of this company together with its lines and taxes. (yazma · onay + geri alınamaz · hepsi · API: delete_invoice_draft)
• lg invoices download — Get a short-lived download link for the PDF of an invoice visible to this company (and the e-invoice XML when one exists). (okuma · — · hepsi · API: download_invoice_pdf)
• lg invoices get — Read one invoice in full: parties, load link, dates, every line with tax, tax breakdown, totals, remaining balance and the payments recorded against it. (okuma · — · hepsi · API: get_invoice)
• lg invoices issue — Issue (finalize) a DRAFT invoice: assigns a number and posts accounting entries. (yazma · onay + geri alınamaz · hepsi · API: issue_invoice)
• lg invoices list — List invoices visible to this company — the ones it issued and the ones issued to it (as a linked party). (okuma · — · hepsi · API: list_invoices)
• lg invoices preview — Show the user a full preview of a DRAFT invoice (recipient, line items, tax breakdown, totals) WITHOUT issuing it. (okuma · — · hepsi · API: preview_invoice · kullanımdan kalkıyor: 2026-09-03 · yerine get_invoice)
• lg invoices reverse-payment — Undo ONE payment/collection recorded on an invoice: posts the reversing journal entry, gives the amount back to the invoice's remaining balance and removes the payment row. (yazma · onay + geri alınamaz · hepsi · API: reverse_invoice_payment)
• lg journal-entries create — Post a manual double-entry journal entry (yevmiye fişi). (yazma · onay + geri alınamaz · hepsi · API: create_journal_entry)
• lg journal-entries get — Read one journal entry with its lines (account code/name, debit, credit, counterparty) and totals. (okuma · — · hepsi · API: get_journal_entry)
• lg journal-entries list — List journal entries (yevmiye fişleri) of the company, newest first, with optional date window. (okuma · — · hepsi · API: list_journal_entries)
• lg load-documents create — File one or MANY documents the user attached to this conversation onto a load: each file is stored as a company document and posted into the load's chat, where every participant (customer, carrier, customs broker) sees… (yazma · onay + geri alınamaz · hepsi · API: attach_chat_file_to_load)
• lg load-documents list — List the documents (CMR, invoice, packing list, customs papers, photos…) filed on a load — i.e. the files shared in that load's chat. (okuma · — · hepsi · API: list_load_documents)
• lg load-groups add-loads — Merge EXISTING loads into a groupage trip you own as consignments (they keep their own code, chat, documents and participants; only the trip membership changes — nothing is duplicated and NO credit is used). (yazma · onay · yük sahibi, nakliyeci · API: add_loads_to_group)
• lg load-groups create — Create a groupage trip (parsiyel/sefer): ONE truck carrying several ISOLATED consignments; each consignment is its own load with its own chat/documents/status and receivers never see each other. (yazma · onay + geri alınamaz · yük sahibi, nakliyeci · API: create_load_group)
• lg load-groups get — Detail of one groupage trip: consignments visible to you (load code, status, receiver, route, driver), planned date, optimised master route summary and stop count. (okuma · — · yük sahibi, nakliyeci · API: get_load_group)
• lg load-groups list — List groupage trips (parsiyel / sefer: one truck, several isolated consignment loads) this company owns or — for carriers — carries, newest first, with visible consignment count and route optimisation state. (okuma · — · yük sahibi, nakliyeci · API: list_load_groups)
• lg load-groups optimize — Re-optimise the master route of a groupage trip you own and RETURN the new itinerary: the ordered stops (pickup → export customs → import customs → dropoff), each stop's address and consignment codes, the total distance… (yazma · — · yük sahibi, nakliyeci · API: optimize_trip_route)
• lg load-groups remove-load — Take one consignment out of a groupage trip you own. (yazma · onay · yük sahibi, nakliyeci · API: remove_load_from_group)
• lg load-types search — Resolve a load/transport type (e.g. (okuma · — · hepsi · API: lookup_load_type)
• lg load-vehicles delete — Detach the fleet equipment from a load: both slots by default, or only the tractor unit / only the trailer. (yazma · onay · hepsi · API: clear_load_equipment)
• lg load-vehicles get — Show which tractor unit (or truck/van) and which trailer are attached to a load, whether they belong to your own fleet, and whether the load can still be changed. (okuma · — · hepsi · API: get_load_equipment)
• lg load-vehicles set — Attach one of your own fleet vehicles to a load: the tractor unit / truck slot (plate) and/or the trailer slot (trailer_plate). (yazma · onay · hepsi · API: assign_vehicle_to_load)
• lg loads assign-driver — Assign one of this company's drivers to a load so the driver sees it in the mobile app and starts reporting position. (yazma · onay · nakliyeci · API: assign_driver_to_load)
• lg loads audit-documents — Cross-check the documents already attached to loads and report, PER LOAD, whether their package counts and gross weights agree. (okuma · — · hepsi · API: audit_load_documents)
• lg loads close-problem — Close the open document-consistency flag of ONE load, from the chat. action=resolved means the contradiction was actually fixed (a corrected document was uploaded); action=dismissed means it was a false alarm and should… (yazma · onay · hepsi · API: resolve_load_problem_flag)
• 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 notifications list — Read the signed-in user's own notification inbox (the bell icon): what happened, which kind of event it was, when, whether it is still unread, and the panel address the notification points at. (okuma · — · hepsi · API: list_notifications)
• lg notifications mark-read — Mark ALL of the signed-in user's unread notifications as read (empty the bell). (yazma · — · hepsi · API: mark_notifications_read)
• lg packages get — Read this company's package and CREDIT balance: how many credits are left, how many the package grants per year, how many were used, the renewal date, and the assistant token usage of the current period (1,000,000… (okuma · — · hepsi · API: get_credit_balance)
• lg pallets add-measurement — Record a NEW measurement for an existing pallet (dimensions in centimetres and/or gross weight in kilograms). (yazma · onay · hepsi · API: add_pallet_measurement)
• lg pallets create — Register a NEW pallet in a warehouse, optionally with its first measurement. warehouse_id is required — resolve the warehouse name with lookup_warehouse first. (yazma · onay · hepsi · API: create_pallet)
• lg pallets extract — Estimate a pallet's content label, dimensions (cm) and gross weight (kg) from photo(s) the user attached to THIS conversation. (yazma · — · hepsi · API: extract_pallet_from_photos)
• lg pallets get — Read one pallet in full: its identity (code, label, SKU, barcode), status, warehouse and area, the FULL measurement history (each row with its source — manual, lidar, arcore or ai_photo — and confidence), how many proof… (okuma · — · hepsi · API: get_pallet)
• lg pallets list — List the pallets of this company: code, label, SKU/barcode, status, which warehouse and area it sits in, its latest measured dimensions (cm) and gross weight, and how many proof photos it has. (okuma · — · hepsi · API: list_pallets)
• lg pallets update — Update an existing pallet: its status (in_stock, in_transit, reserved, shipped, disposed), its label/SKU/barcode/note, or MOVE it to another warehouse or area. (yazma · onay · hepsi · API: update_pallet)
• lg payables list — Payables ("whom do we owe how much"): per-supplier totals of recorded purchase invoices — invoiced, paid, remaining, earliest due date — with a per-currency breakdown and an overall summary. (okuma · — · hepsi · API: list_payables)
• lg payment-instructions get — Read one bank payment instruction: its code, template, effective date, status with timestamps and cancel reason, its note, and — when the PDF has already been rendered — a short-lived signed link to it so the user gets… (okuma · — · hepsi · API: get_settlement_instruction)
• lg payment-instructions list — List the bank payment instructions of this company: instruction code, which template (bank format) it uses, its effective date, status (pending, executed, cancelled) and when it was executed or cancelled. (okuma · — · hepsi · API: list_settlement_instructions)
• lg plans archive — Close a plan because the user says the work is finished or abandoned. (yazma · — · hepsi · API: archive_plan)
• lg plans create — Write down a multi-step job so it survives between conversations ("link these 5 loads to a trip, then invoice them"). (yazma · onay · hepsi · API: create_plan)
• lg plans get — Read one plan: the steps that were agreed AND the commands that actually ran while it was active. (okuma · — · hepsi · API: get_plan)
• lg plans list — List this company's plans, newest first. (okuma · — · hepsi · API: list_plans)
• lg preferences create — Remember a lasting preference of THIS user, so it applies to every future conversation too ("always show amounts in EUR", "write driver names surname first", "I want the weekly summary on Mondays"). (yazma · — · hepsi · API: remember_preference)
• lg preferences delete — Forget one stored preference of this user. (yazma · — · hepsi · API: forget_preference)
• lg preferences list — List what you have been asked to remember about THIS user, with the labels. (okuma · — · hepsi · API: list_preferences)
• lg products create — Define a new product in this company's catalogue so stock can be recorded against it: name plus optionally its unit of measure, SKU, barcode, category, brand, minimum stock level, reorder quantity and lot tracking. (yazma · onay · yük sahibi · API: create_product)
• lg products list — List the products of this company: code, name, SKU/barcode, unit, category and brand, whether it is active, and its low-stock threshold. (okuma · — · yük sahibi · API: list_products)
• lg products list-low-stock — List the products that have fallen to or below their low-stock threshold, with the quantity on hand and the threshold itself. (okuma · — · yük sahibi · API: list_low_stock_products)
• lg products search — Resolve a product to its product_id + on-hand quantity. (okuma · — · yük sahibi · API: lookup_product)
• lg products update — Correct an existing product: its name, unit, SKU, barcode, category, brand, minimum stock level, reorder quantity, lot tracking, note, or whether it is active. (yazma · onay · yük sahibi · API: update_product)
• lg receivables get — Account statement of one contact: every sales invoice issued to them and every collection, in date order with a running balance, plus totals (invoiced, paid, open balance, open invoice count). (okuma · — · hepsi · API: get_receivable_statement)
• lg receivables list — Receivables ("who owes us how much"): per-contact totals of issued sales invoices — invoiced, paid, remaining — with a per-currency breakdown and an overall summary. (okuma · — · hepsi · API: list_receivables)
• lg reports get — Financial reports from posted journal entries: trial_balance (per-account debit/credit/balance as of a date), balance_sheet (as of a date) or income_statement (revenues/expenses/net income for a date range; defaults to… (okuma · — · hepsi · API: get_accounting_report)
• lg reservations approve — As the warehouse owner, approve a pending reservation received at your warehouse (the booker is notified). (yazma · onay · yük sahibi · API: approve_reservation)
• lg reservations cancel — Cancel (withdraw) a warehouse reservation you booked, or — as the warehouse owner (customer) — cancel a reservation received at your warehouse. (yazma · onay + geri alınamaz · hepsi · API: cancel_reservation)
• lg reservations create — Book a warehouse dock time slot. (yazma · onay · hepsi · API: create_reservation)
• lg reservations get — Detail of one warehouse reservation you booked or (customer) one received at your warehouse: warehouse, area, time window, status, contact, notes, rejection reason. (okuma · — · hepsi · API: get_reservation)
• lg reservations list — List warehouse dock reservations. side=booked_by_me (default): reservations this user/company booked at other companies' warehouses. side=received (customer role only): reservations other companies made at ONE of your… (okuma · — · hepsi · API: list_reservations)
• lg reservations list-slots — For a warehouse reservation link (the token at the end of a https://…/public/reservation/ link a warehouse owner shared), show the warehouse (name, owner company, working hours, rules) and the available dock time… (okuma · — · hepsi · API: list_reservation_slots)
• lg reservations reject — As the warehouse owner, reject a pending reservation received at your warehouse, with an optional reason shown to the booker. (yazma · onay + geri alınamaz · yük sahibi · API: reject_reservation)
• lg roro-routes list — For a load you are carrying, list the Ro-Ro (ferry) lines closest to its PICKUP address, nearest first: the line name, its departure and arrival ports and how many kilometres the pickup point is from the departure port. (okuma · — · nakliyeci · API: list_nearby_roro_routes)
• lg roro-routes select — Select the Ro-Ro (ferry) line a load you are carrying will use. (yazma · onay · nakliyeci · API: select_roro_route)
• lg roro-routes set-required — Mark whether a load you are carrying will travel by Ro-Ro (ferry) or not. (yazma · onay · nakliyeci · API: set_load_roro_required)
• lg settlements create — Close several open invoices of ONE contact in ONE currency in a single bulk collection (direction in) or bulk payment (direction out). instrument transfer = money already moved by bank transfer (payments + journal… (yazma · onay + geri alınamaz · hepsi · API: create_settlement_batch)
• lg settlements list — List bulk collection/payment batches (code, direction, instrument, contact, currency, total, value date, status), newest first. (okuma · — · hepsi · API: list_settlement_batches)
• lg settlements list-invoices — Open LOCAL invoices of one contact in one currency that can be allocated in a bulk collection (direction in = sales invoices) or bulk payment (direction out = purchase invoices), each with payable_remaining (remaining… (okuma · — · hepsi · API: list_settlement_invoices)
• 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 list-movements — List the stock movements of this company, newest first: which product moved, in or out (or a transfer or a count adjustment), how much, in which warehouse and area, on which pallet, who performed it and when. (okuma · — · yük sahibi · API: list_stock_movements)
• 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 tariff-chapters get — Answer "which chapter is this GTİP in / what does chapter 76 cover / what do the chapter notes say?". (okuma · — · hepsi · API: get_tariff_chapter)
• lg tariff-matrices get — FREE. (okuma · — · hepsi · API: get_tariff_matrix)
• lg tariff-matrices list — FREE. (okuma · — · hepsi · API: list_tariff_matrix_runs)
• lg tariff-matrices preview — FREE. (okuma · — · hepsi · API: plan_tariff_matrix)
• lg tariff-matrices run — Run an official duty + anti-dumping inquiry for ONE tariff code across MANY origin and destination countries at once, and record it. (yazma · onay + geri alınamaz · hepsi · API: run_tariff_matrix)
• lg tariffs coverage — FREE. (okuma · — · hepsi · API: get_tariff_coverage)
• lg tariffs extract — Read an invoice or proforma the user attached to THIS conversation and pull out its product lines with candidate GTİP/HS codes, plus the origin and destination it names. (yazma · — · hepsi · API: extract_tariff_codes_from_invoice)
• lg tariffs get — Read the result of a tariff inquiry that was already run: duty rate, the column it came from, the statutory rate, anti-dumping measures and the data notes. (okuma · — · hepsi · API: get_tariff_inquiry)
• lg tariffs inquiry — Start an official duty / anti-dumping inquiry for one GTİP/HS code and a COUNTRY PAIR (origin → destination). (yazma · onay + geri alınamaz · hepsi · API: run_tariff_inquiry)
• lg tariffs list — List this company's recent tariff inquiries (code, direction, counterpart country, status, date) so the user can find an earlier one by code or country instead of running a new inquiry. (okuma · — · hepsi · API: list_tariff_inquiries)
• lg tariffs search — Search the Turkish customs nomenclature (GTİP / HS) by goods description or by a partial code, and return matching codes with their official descriptions. (okuma · — · hepsi · API: lookup_tariff_code)
• lg teammates delete — Remove a person from the company team. (yazma · onay + geri alınamaz · hepsi · API: remove_teammate)
• lg teammates list — List the other users of this company (drivers excluded) with e-mail, active state and RBAC role (manager | employee | fleet-manager). (okuma · — · hepsi · API: list_teammates)
• lg teammates set-role — Change a team member's role (for example make them a manager, or move them back to employee). (yazma · onay · hepsi · API: update_teammate_role)
• lg teammates set-status — Activate or deactivate a team member. (yazma · onay · hepsi · API: set_teammate_status)
• lg tender-bids create — Submit YOUR bid for a tender using a file the user attached to THIS conversation (the filled specification spreadsheet, a PDF offer, or a zip). (yazma · onay + geri alınamaz · nakliyeci · API: submit_tender_bid)
• lg tender-bids get — Read YOUR OWN bid on a tender: its status (submitted, revision requested, accepted, rejected), when it was submitted and which files it carries. (okuma · — · nakliyeci · API: get_my_tender_bid)
• lg tender-bids set-status — As the tender owner, ACCEPT a carrier's bid, REJECT it, or ask for a REVISION. (yazma · onay + geri alınamaz · yük sahibi · API: decide_tender_bid)
• lg tenders create — Open a NEW document-based freight tender and generate its specification Excel from the lanes the user gives (origin → destination, vehicle/load type, monthly volume). (yazma · onay · yük sahibi · API: create_tender)
• lg tenders generate — Generate a specification Excel for an EXISTING tender from the lanes/items the user gives and attach it to the tender as a document; returns a short-lived download link. (yazma · onay · yük sahibi · API: generate_tender_excel)
• lg tenders get — Read one tender in full: specification text, dates, attached specification files (with short-lived download links) and — for the tender owner — every carrier bid with its status; a carrier sees only its own bid. (okuma · — · yük sahibi, nakliyeci · API: get_tender)
• lg tenders list — List document-based freight tenders. (okuma · — · yük sahibi, nakliyeci · API: list_tenders)
• lg trade-measures get — Answer "is there an anti-dumping / countervailing / safeguard measure on this GTİP code when importing INTO TURKEY?" straight from the Ministry of Trade's measures-in-force list, which we sync every day. (okuma · — · hepsi · API: get_trade_measures)
• lg trade-measures list — Browse Türkiye's trade-defence measures WITHOUT a GTİP code: by origin country ("which measures apply to goods from China"), by product ("which countries have a measure on aluminium foil"), by measure type, or by end… (okuma · — · hepsi · API: list_trade_measures)
• lg vehicle-assignments create — Hand a fleet vehicle over to a driver (open an assignment), so their expense receipts and trips are attached to the right tractor unit or trailer. (yazma · onay · yük sahibi, nakliyeci · API: assign_vehicle_to_driver)
• lg vehicle-assignments list — List which driver currently holds which vehicle (tractor unit / trailer). (okuma · — · yük sahibi, nakliyeci · API: list_vehicle_assignments)
• lg vehicle-assignments revoke — Close an open vehicle assignment: the driver hands the vehicle back. (yazma · onay · yük sahibi, nakliyeci · API: end_vehicle_assignment)
• lg vehicle-expenses create — Record a cost against one of the company's own vehicles without an invoice file — category, amount and currency are required, the rest is optional. (yazma · onay · yük sahibi, nakliyeci · API: create_vehicle_expense)
• lg vehicle-expenses list — List the cost records of the company's own vehicles (maintenance, tyres, repair, roadworthiness test, insurance, fuel, tolls, parts) with a EUR total and a breakdown per category and per currency. (okuma · — · yük sahibi, nakliyeci · API: list_vehicle_expenses)
• lg vehicles archive — Take a vehicle out of service (archive it) or put an archived one back into service. (yazma · onay · yük sahibi, nakliyeci · API: archive_vehicle)
• lg vehicles create — Add a vehicle to this company's fleet: plate plus its kind (truck, tractor unit, trailer, van, pickup, car), optionally brand, model, model year, VIN and a note. (yazma · onay · yük sahibi, nakliyeci · API: create_vehicle)
• lg vehicles get — Full detail of ONE fleet vehicle: identity (plate, kind, brand, model, model year, VIN), whether it is active or archived, ALL of its papers with their expiry date and days_to_expiry, how many papers expire soon or… (okuma · — · yük sahibi, nakliyeci · API: get_vehicle)
• lg vehicles list — List this company's fleet vehicles with plate, kind (truck / tractor unit / trailer / van / pickup / car), brand, model, model year, VIN and how many of their papers (insurance, inspection, permits) expire soon or have… (okuma · — · yük sahibi, nakliyeci · API: list_vehicles)
• lg vehicles search — Resolve one of this company's fleet vehicles (truck, tractor unit, trailer, van, pickup, car) to its vehicle_id by plate, brand, model or VIN. (okuma · — · yük sahibi, nakliyeci · API: lookup_vehicle)
• lg vehicles update — Correct a fleet vehicle's fields: plate, kind, brand, model, model year, VIN or note. (yazma · onay · yük sahibi, nakliyeci · API: update_vehicle)
• lg warehouses create — Define a new warehouse for this company so stock can be held and dock slots booked there: a name and its street address are enough. (yazma · onay · yük sahibi · API: create_warehouse)
• lg warehouses get — Read one warehouse in full: its identity and address, working days and hours, holiday opening, capacity, reservation slot rules (slot length, minimum and maximum duration), its safety and driver rules, the… (okuma · — · yük sahibi · API: get_warehouse)
• lg warehouses list — List the warehouses of this company: name, address, whether it is active, its working days and hours, open/closed area capacity, the dock slot length and how many areas (racks/bays) it has. (okuma · — · yük sahibi · API: list_warehouses)
• lg warehouses search — Resolve a warehouse by name to its warehouse_id, with its areas. (okuma · — · yük sahibi · API: lookup_warehouse)
• lg warehouses update — Update a warehouse: its name or address, working days and hours, holiday opening, capacity, dock slot rules, the driver/safety flags or the active flag. (yazma · onay · yük sahibi · API: update_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.
• 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. Bugün kullanımdan kalkmış komut yoktur.

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.
• Yapay zekâ ya da kredi harcayan komutlar (tariffs inquiry, export-documents extract, export-documents generate): gerçek sınır istek sayısı değil KREDİDİR. Bir 200 yanıtı bir kredi harcamış olabilir.
• 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.
• İ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ı. 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.

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.
• 246 operasyon — 207 komut + 35 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ı 185, bir nakliyeci 181, bir gümrük müşaviri 122 komut metodu üretir. Kimliksiz kamu tanımından üretirseniz üst sınır 246 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 185 komut); kamu tanımından üretirseniz 246 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ı 185, nakliyeci 181, gümrük müşaviri 122 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 — 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 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.

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?

Panelde Ayarlar › Entegrasyon anahtarları bölümünden, ekip yönetimi yetkisi olan bir yönetici üretir. Anahtar gerçek bir ekip üyesi adına çalışır; yalnız-okuma kapsamı katalog ve yazmayan komutları, okuma+yazma kapsamı tüm komutları (onay kapısı aynen kalarak) açar. Bir kez gösterilir, sunucuda saklanmaz; yenilenebilir 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â 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.