Logistivo CLI: jalankan operasi logistik Anda dari terminal dan dari ERP Anda
Satu katalog perintah melayani tiga antarmuka: klien terminal lg, asisten AI di dalam dashboard, dan kanal yang digunakan asisten AI eksternal untuk terhubung. Sebuah kemampuan ditulis sekali dan muncul di ketiganya — dan kini setiap tindakan tulis di panel memiliki perintah, sehingga skrip Anda dan agen AI Anda sendiri dapat mengerjakan pekerjaan yang dilakukan tim Anda di layar. Pembayaran, persetujuan hukum, dan penutupan akun sengaja tetap berada di browser. Halaman ini adalah sebuah kontrak. Tabel perintah di bawah tidak ditulis tangan; tabel itu dibuat dari registri perintah yang aktif pada setiap permintaan.
Apa itu Logistivo CLI?
Logistivo CLI (lg) adalah klien baris perintah yang menjalankan pekerjaan akun Logistivo Anda — muatan dan perjalanan, permintaan angkutan, penawaran dan tender, armada dan pengemudi, dokumen, kontak dan rekening berjalan, faktur dan akuntansi, gudang dan stok, anggota tim, serta tarif bea cukai — dari terminal, skrip, atau agen AI Anda sendiri. Perintah-perintahnya tidak tertanam di dalam klien: klien mengambil katalog perintah dari server dan membangun tampilannya sendiri dari katalog itu. Perintah yang sama dapat dipanggil melalui HTTP tanpa memasang apa pun — itulah jalur yang digunakan integrasi ERP dan CRM — dan melalui kanal MCP yang digunakan asisten AI eksternal untuk terhubung.
Satu bentuk perintah: lg --parameter=value. Saat ini katalog memuat 721 perintah di 175 domain; daftar terluas yang dilihat oleh satu peran adalah 646 perintah di 165 domain.
Setiap tindakan tulis di panel memiliki perintah — diukur terhadap endpoint tulis panel, 100% endpoint yang termasuk dalam cakupan sudah tercakup. Pembayaran (3D Secure), persetujuan hukum, dan penutupan akun sengaja tetap di browser; untuk hal-hal tersebut, perintah mengembalikan sebuah tautan.
Perintah yang menerima dokumen atau foto juga berfungsi di luar browser: tulis --attachment_uuid=@./cmr.pdf dan lg akan mengunggah file tersebut terlebih dahulu; melalui HTTP, Anda mengunggah ke /api/common/commands:upload lalu meneruskan attachment_uuid yang dikembalikan.
Kunci integrasi membawa tingkat akses: employee (bawaan untuk kunci baru) untuk operasi sehari-hari, manager untuk tim, pengaturan, kunci, dan uang. Sebuah kunci tidak pernah memiliki hak lebih banyak daripada orang yang diwakilinya.
Flag tidak pernah dikarang: setiap flag adalah nama parameter dari JSON Schema milik perintah itu sendiri, demikian pula tipenya dan apakah flag itu wajib.
Perintah tulis meminta konfirmasi; perintah yang tidak dapat dibatalkan tidak pernah berjalan tanpa konfirmasi (HTTP 409, kode keluar CLI 4).
Mencoba ulang tidak menghasilkan duplikat: panggilan yang membawa idempotency_key dijalankan paling banyak satu kali.
Setiap eksekusi tercatat dalam satu log audit — apakah eksekusi itu berasal dari terminal, dari chat, atau dari asisten, semuanya tercatat.
Apa yang sudah aktif hari ini, dan apa yang sedang disiapkan
Bagian ini sengaja diletakkan di bagian atas halaman. Kesalahan paling mahal yang dapat dibuat oleh sebuah dokumen integrasi adalah mendeskripsikan endpoint yang belum dibuka seolah-olah sudah dibuka: integrator menulis kodenya, endpoint mengembalikan 404, dan kepercayaan tidak pernah kembali.
Karena kontraknya dibekukan, kode integrasi yang Anda tulis hari ini tetap berfungsi saat bagian-bagian yang tersisa dibuka. Field yang tidak Anda kenal harus diabaikan; aturan itulah yang memungkinkan kami menambahkan hal baru tanpa merusak yang lama.
Katalog perintah dan tabel identitas — Identitas domain/verb publik setiap perintah telah dibekukan, dan versi kontrak dipublikasikan sebagai 1 di setiap respons katalog dan di header X-Contract-Version. Tabel di halaman ini dibuat dari registri yang aktif: perintah yang ditambahkan di server muncul di sini dengan sendirinya, dan perintah yang dihapus akan hilang.
Endpoint penemuan tanpa autentikasi — GET /api/public/cli/catalog — nama perintah, identitas domain/verb, deskripsi, parameter JSON Schema, flag gerbang, dan field versioning (since, deprecated_at, replaced_by, aliases). Tanpa autentikasi: membuat token adalah langkah yang datang SETELAH keputusan integrasi, bukan sebelumnya. Respons ini sama sekali tidak memuat data tenant.
Endpoint katalog dan eksekusi dengan autentikasi — GET /api/common/commands, GET /api/common/commands/{name} dan POST /api/common/commands/{name}. Gerbang peran, gerbang konfirmasi, idempotency, dan log audit berada di satu titik penegakan yang juga dilalui oleh chat dan terminal.
Cakupan panel: setiap tindakan tulis memiliki perintah — 721 perintah di 175 domain, diperiksa terhadap endpoint tulis panel: setiap endpoint dalam cakupan didukung oleh sebuah perintah (cerminan dari endpoint tersebut atau layanan bersama yang sama), dan tidak ada satu pun yang belum terbukti. Sengaja berada di luar cakupan: pembayaran dengan 3D Secure, persetujuan hukum, penutupan akun, dan proses masuk (sign-in), yang tetap di browser; pengelolaan kunci, webhook, dan sandbox, yang merupakan perintah bawaan lg; serta endpoint milik aplikasi pengemudi sendiri.
Preflight (dry_run): lihat hasilnya tanpa menjalankannya — Dengan dry_run: true di body permintaan, perintah tidak dijalankan: validasi, gerbang peran/scope, resolusi target, dan perhitungan kredit semuanya dieksekusi dan sebuah pratinjau dikembalikan; tidak ada yang ditulis, tidak ada kredit yang terpakai, dan idempotency key tidak dikonsumsi. Endpoint batch juga menerimanya, per batch. Preflight tidak pernah masuk ke handler perintah; ketika fitur ini dirilis, 178 preflight di seluruh perintah tulis yang ada di katalog saat itu tidak menghasilkan satu pun pernyataan tulis.
Kunci integrasi — Kunci API yang bertindak atas nama anggota tim yang nyata, diterbitkan di panel atau dengan lg keys create: scope baca/tulis, tingkat akses (employee secara bawaan, atau manager), masa berlaku, penggunaan terakhir, rotasi, transfer, dan pencabutan. lg login --api-key, lg whoami, dan lg logout yang mencabut kunci di sisi server dibangun di atasnya.
Sandbox — latih penulisan tanpa menyentuh produksi — Tenant sandbox terpisah untuk setiap perusahaan dengan katalog perintah yang sama; dibuka secara mandiri (self-service) dan menerbitkan kuncinya sendiri. Kredit, marketplace, dan perutean webhook dipisahkan antara kedua lingkungan; lingkungan ditentukan dari perusahaan pemilik kunci dan tidak dapat disertakan dalam permintaan.
Versioning, taksonomi error, idempotency, dan rate limit — Perintah membawa since / deprecated_at / replaced_by / aliases, dan perintah yang sudah usang (deprecated) menjawab dengan header X-Deprecated. Kegagalan bisnis membawa error_key yang stabil di samping error_code tingkat transport, dan kamus kuncinya dipublikasikan di katalog. Idempotency key dibatasi pada perusahaan Anda, terikat pada satu perintah, dan dikunci selama 24 jam. Rate limit (batas laju) berlaku per token, dalam tiga bucket, dan setiap 429 membawa Retry-After.
Webhook keluar: sebuah POST ketika sesuatu terjadi — Push bertanda tangan sudah aktif untuk 13 event. Langganan dikelola dari panel atau dengan lg webhooks; tanda tangan membawa stempel waktunya sendiri, jadwal percobaan ulang adalah 60 · 300 · 1800 · 7200 · 21600 detik, dan alasan penonaktifan selalu dicatat. Setiap nama event didukung oleh kelas event yang benar-benar di-dispatch — tidak ada yang diumumkan lalu tidak pernah dikirim. Jalur pull (updated_since + cursor) tidak dihapus: push ditambahkan di sampingnya, bukan sebagai penggantinya.
Perintah yang menerima file — 38 perintah menerima dokumen atau foto — CMR, faktur, dokumen registrasi kendaraan, foto palet. Unggah sekali ke POST /api/common/commands:upload, atau biarkan lg melakukannya dengan --attachment_uuid=@./file.pdf, lalu teruskan attachment_uuid yang dikembalikan; klien MCP menggunakan tool upload_attachment. Tipe file dideteksi dari isinya, dan sebuah unggahan tetap dapat digunakan selama 24 jam.
Klien terminal lg — Dipublikasikan di npm dengan lisensi MIT: pasang dengan `npm install -g @lgstv/lg`, atau jalankan tanpa memasang melalui `npx @lgstv/lg`. Klien ini berupa satu file tanpa dependensi, dan karena antarmuka HTTP-nya terbuka, Anda dapat berintegrasi tanpa klien ini. Klien ini masuk dengan kode persetujuan yang Anda konfirmasi di browser, lalu tetap dalam keadaan masuk sambil memperbarui sesinya dengan sendirinya; klien ini mengunggah file lokal untuk Anda (@path, --file, lg upload), mengelola kunci integrasi (lg keys), tidak pernah menerima secret di baris perintah, mematuhi Retry-After, mencoba ulang 5xx dengan idempotency key yang sama, dan memberi peringatan untuk perintah yang usang serta versi kontrak yang lebih baru.
Sinkronisasi inkremental: paginasi cursor dan updated_since — Kontrak di bawah ini (limit + cursor opaque yang bertanda tangan, next_cursor, updated_since) sudah ditetapkan dan sedang diterapkan secara bertahap di seluruh perintah daftar. Sampai sebuah perintah daftar mencantumkan cursor dan updated_since di JSON Schema-nya, perlakukan perintah itu sebagai jendela kecil: batas atas 20 baris, tanpa cursor.
Apa yang membuatnya berbeda: klien tidak mengenal satu pun perintah, klien menampilkannya dari katalog
Inilah satu keputusan yang membuat seluruh isi halaman ini bermakna. Pada CLI biasa, perintah berada di dalam klien; di Logistivo, perintah berada di server.
Dalam susunan klasik, ketika server memperoleh kemampuan baru, klien memerlukan rilis baru dan pengguna perlu memasangnya. Di antara kedua momen itu, kedua sisi mengetahui hal yang berbeda — dan itulah mode kegagalan paling senyap dalam integrasi: skrip berjalan, kode keluarnya 0, dan perintah itu begitu saja tidak menggambarkan apa yang dapat dilakukan server.
Di Logistivo, definisi sebuah perintah adalah satu rekaman: namanya, apa yang dilakukannya, parameter JSON Schema-nya, peran mana yang boleh melihatnya, apakah perintah itu memerlukan konfirmasi, dan apakah efeknya dapat dibatalkan. Saat lg dijalankan, ia mengambil katalog tersebut dan menghasilkan teks bantuan, flag, serta validasi input-nya dari katalog itu. Begitu sebuah perintah ditambahkan di server, lg langsung mengenalnya — tanpa pembaruan klien.
Katalog yang sama melayani asisten AI di dashboard dan kanal yang digunakan asisten AI eksternal untuk terhubung. Sebuah kemampuan ditulis sekali dan muncul di tiga tempat — dan ketiganya melewati gerbang peran yang sama, gerbang konfirmasi yang sama, dan log audit yang sama. Tidak ada inventaris perintah CLI yang terpisah; jika ada, ketiga antarmuka itu akan diam-diam saling menyimpang dalam enam bulan.
Tidak ada selisih versi — Daftar perintah yang dikenal klien, secara konstruksi, adalah daftar yang dimiliki server. "Versi lg mana yang memiliki perintah ini?" bukanlah pertanyaan yang ada.
Nama flag tidak pernah ditebak — Flag sebuah perintah persis sama dengan nama-nama parameter di JSON Schema-nya. Cara untuk mengetahui apa yang diterima sebuah perintah bukanlah membaca dokumen, melainkan membaca katalog — dan katalog selalu mutakhir.
CLI Anda sebesar akun Anda — Katalog difilter berdasarkan peran: perintah yang tidak dapat dilihat oleh peran Anda tidak pernah muncul di daftar Anda. Akun pengangkut (carrier) melihat 621 perintah, pengirim (shipper) 646, agen kepabeanan (customs broker) 392, dan akun afiliasi (mitra rujukan) memiliki set tersendiri, yaitu 55 perintah.
Dokumentasi tidak bisa tertinggal — Tabel perintah di halaman ini berasal dari registri yang sama. Tidak ada daftar di mana pun yang harus diselaraskan secara manual dengan kenyataan.
Aturan penamaan — bagaimana nama perintah bertambah
Katalog akan terus bertambah. Perintah baru tidak diberi nama secara asal; ada enam aturan yang diterapkan. Kami memublikasikannya di sini karena inilah nama-nama yang akan ditulis oleh integrasi Anda selama bertahun-tahun, dan keterdugaannya bernilai bagi Anda.
Domain adalah entitas dalam bentuk jamak — loads, demands, invoices, export-documents. Domain dua kata ditulis dalam kebab-case. Satu-satunya pengecualian adalah kata benda yang tidak dapat dihitung: stock tidak pernah dijamakkan, karena "stocks" berarti hal lain (saham).
Semua verb dari satu entitas berada dalam satu domain — loads memuat setiap verb yang bekerja pada sebuah muatan: create, list, get, update, set-status, assign-driver, list-problems, archive, dan lainnya. Membuka domain baru untuk setiap verb (load-statuses, load-drivers) akan membuat pengguna mencari entitas yang sama di tiga tempat.
Verb tidak pernah bocor ke dalam domain; domain adalah hal yang BERUBAH — Menugaskan pengemudi mengubah muatan, bukan pengemudinya, sehingga perintahnya adalah lg loads assign-driver. Objek tidak langsung (-driver) dilekatkan pada verb, tidak pernah pada domain.
Sub-resource tidak pernah mendapat domain sendiri — Baris faktur dan item dokumen tidak dapat ditampilkan secara mandiri; keduanya diakses melalui pemiliknya — lg invoices add-line, lg export-documents add-item. Satu uji yang menentukannya: jika Anda tidak dapat menjalankan list atau get untuk hal itu secara mandiri, maka hal itu bukan domain.
Penyempitan adalah flag, bukan verb baru — lg fleet-documents list --days=30 adalah bentuk yang benar; tidak ada verb "list-expiring" tersendiri, karena jendela waktunya sudah berupa parameter. Verb yang dikualifikasi hanya digunakan bila baris yang dikembalikannya bukan entitas domain itu: loads list-problems mengembalikan penanda masalah, bukan muatan.
Pasangan (domain, verb) unik di seluruh katalog — Bahkan untuk dua perintah yang perannya tidak pernah tumpang tindih. Jika pasangan yang sama diberikan kepada dua perintah, kode integrasi Anda akan melihat satu nama sementara CLI menjalankan hal yang berbeda tergantung siapa yang memanggilnya.
Cakupan: semua yang ada di panel, dari sebuah perintah
Banyak tim menghubungkan Logistivo ke agen AI atau harness otomasi milik mereka sendiri, dan sebuah agen hanya berguna jika dapat menyelesaikan pekerjaannya. Karena itu, aturannya sederhana: apa pun yang dapat diubah oleh pengguna kantor di panel, dapat diubah juga oleh sebuah perintah — di balik gerbang peran yang sama, gerbang konfirmasi yang sama, dan log audit yang sama.
Hal ini diukur, bukan sekadar diklaim. Setiap endpoint tulis di balik panel diperiksa terhadap registri perintah, dan sebuah endpoint baru dihitung tercakup jika ada perintah yang menyatakannya sebagai cerminan HTTP-nya atau memanggil layanan bersama yang sama. Dari endpoint tulis yang termasuk dalam cakupan, 100% sudah tercakup dan tidak ada satu pun yang belum terbukti. Setiap endpoint yang tidak disertakan memiliki alasan tertulis — langkah identitas dan pembayaran, control plane integrasi, endpoint milik aplikasi pengemudi sendiri, telemetri klien, salinan mati tanpa pemanggil — dan endpoint yang penting bagi integrator tercantum di bawah ini.
Perintah yang menerima file tunduk pada aturan yang sama: 38 perintah di tabel menerima dokumen atau foto, dan semuanya berfungsi dari lg, melalui HTTP, dan melalui MCP (lihat Perintah yang menerima file).
Pekerjaan manajemen juga tercakup, di balik kunci yang lebih kuat: 87 perintah di tabel — anggota tim dan peran, pengaturan perusahaan, rekening bank, kartu tersimpan, kunci integrasi — memerlukan kunci integrasi tingkat manager. Kunci tingkat employee, yang merupakan bawaan, menjalankan operasi sehari-hari dan ditolak untuk perintah-perintah tersebut dengan INSUFFICIENT_KEY_LEVEL.
Akun afiliasi (mitra rujukan) memiliki katalognya sendiri: 55 perintah di 20 domain — rujukan, prospek (lead), catatan dan tugas CRM, materi presentasi penjualan, pendapatan dan pembayaran, ditambah perintah akun dan tim yang dimiliki setiap peran. Perintah khusus afiliasi tidak ada di tabel publik di bawah, yang mencantumkan tiga peran panel; akun afiliasi melihatnya di GET /api/common/commands dan di lg commands. Perusahaan yang sekaligus merupakan afiliasi dan pengirim, pengangkut, atau agen kepabeanan melihat kedua set tersebut.
Sebuah agen sebaiknya memulai dengan lg users get (nama API get_current_user): perintah ini mengembalikan peran, tingkat akses kunci yang sedang digunakan, izin yang efektif, dan apakah ada persetujuan hukum yang tertunda atau nomor telepon yang belum diverifikasi yang saat ini memblokir penulisan — sehingga agen dapat memprediksi penolakan alih-alih mengumpulkannya.
Cakupan diukur oleh sebuah laporan yang membandingkan registri perintah dengan endpoint tulis panel; endpoint panel yang ditambahkan tanpa perintah akan muncul di laporan itu sebagai belum terbukti. Jika Anda menemukan tindakan di panel yang tidak dapat Anda jangkau dari sebuah perintah, laporkan kepada tim dukungan.
1. Minta tautannya — Pekerjaan yang harus terjadi di sesi browser milik orang itu sendiri bukanlah perintah, tetapi permukaan perintah mengetahuinya. lg handoff-links generate (nama API get_browser_handoff_link) mengembalikan tautan logistivo.com untuk tujuan-tujuan yang diizinkan oleh peran Anda: package_purchase, payment_cards, legal_documents, integration_keys, affiliate_demo_accounts, dan account_close. Perintah ini gratis, tidak menulis apa pun, dan tautannya tidak membawa secret — orang itu masuk seperti biasa.
2. Serahkan kepada orang yang bersangkutan — Tampilkan tautan kepada pengguna atau kirimkan melalui kanal Anda sendiri. Mereka menyelesaikan langkahnya di sana: persetujuan kontrak dan pembayaran 3D Secure untuk sebuah paket, menambahkan kartu, menyetujui teks hukum yang tertunda, menerbitkan kunci API yang secret-nya ditampilkan satu kali, atau menutup akun mereka sendiri.
3. Baca hasilnya dengan sebuah perintah — Setelah langkah itu selesai, hasilnya kembali terlihat oleh perintah: paket dan saldo kredit, kartu yang tersimpan (disamarkan, hanya empat digit terakhir), kunci baru di daftar kunci. Agen tidak pernah menerima nomor kartu, pembayaran, atau persetujuan di dalam chat.
Pembayaran dan 3D Secure — Membeli atau meningkatkan paket dan menambahkan kartu memerlukan 3D Secure di browser. Perintah dapat menampilkan daftar paket dan harga, membaca saldo beserta riwayatnya, menampilkan daftar kartu tersimpan (disamarkan), menetapkan kartu bawaan, dan menghapus kartu; pembelian itu sendiri berjalan melalui tautan handoff.
Persetujuan hukum — Menyetujui teks hukum dilakukan oleh orang yang bersangkutan, di browser. lg users get memberi tahu Anda bahwa ada persetujuan yang tertunda; tidak ada perintah yang dapat memberikannya.
Penutupan akun, proses masuk, dan kata sandi — Menutup akun Anda sendiri, masuk (sign-in), dan mengubah kata sandi adalah langkah identitas dan tetap berada di browser. lg user-accounts preview menunjukkan apa arti penutupan akun, tanpa melakukannya.
Kunci integrasi, webhook, dan sandbox — Mengelolanya menghasilkan secret yang harus ditampilkan satu kali, di terminal Anda, sehingga semuanya merupakan perintah bawaan lg (lg keys, lg webhooks, lg sandbox) di atas endpoint HTTP-nya sendiri, bukan perintah katalog. Katalog hanya memuat dua perintah kunci yang bebas secret: integration-keys list dan integration-keys revoke.
Chat asisten di dashboard — Kunci integrasi tidak dapat mengendalikan chat asisten AI di dalam dashboard; memulai atau melanjutkan eksekusi dengan sebuah kunci menjawab 403. Sebagai gantinya, agen terhubung melalui endpoint perintah, lg, atau kanal MCP — di sana setiap perintah berjalan pada tingkat akses kunci dan penulisannya dicatat sebagai penulisan integrasi.
Aplikasi pengemudi — Akun pengemudi tidak memiliki katalog perintah, dan aplikasi pengemudi mempertahankan endpoint-nya sendiri. Pengguna kantor mengelola pengemudi, dokumen mereka, pengeluaran, dan perjalanan melalui perintah.
Instalasi dan identitas
lg adalah skrip Node satu file tanpa dependensi (Node 18+), dipublikasikan di npm sebagai @lgstv/lg. Paket ini memasang dua perintah yang identik, lg dan logistivo — gunakan logistivo jika lg sudah menjadi alias di mesin Anda. Karena hanya satu file, menyalin lg.mjs ke server ERP pelanggan juga bisa dilakukan. Anda tidak memerlukan klien ini untuk membangun integrasi ERP/CRM — perintah yang sama tersedia melalui HTTP.
1. Instalasi — Yang Anda butuhkan hanyalah Node 18 atau yang lebih baru; tidak ada dependensi lain. Pasang secara global atau jalankan tanpa memasang melalui npx.
2. Masuk dengan kode persetujuan — lg login menampilkan kode persetujuan yang pendek dan membuka logistivo.com/connect di browser Anda; melalui SSH, di CI, atau dengan --no-browser, perintah ini hanya mencetak alamatnya, yang dapat Anda buka di perangkat apa pun, termasuk ponsel Anda. Masuklah di sana seperti biasa, periksa bahwa kode di halaman itu sama dengan kode di terminal Anda, pilih akses hanya-baca atau baca-dan-bertindak, lalu setujui. Tidak ada hal rahasia yang diketik di terminal: tidak ada kata sandi, tidak ada kunci, tidak ada kode sekali pakai. Setelah itu sesi tetap dalam keadaan masuk di komputer tersebut — menutup terminal tidak membuat Anda keluar, dan lg memperbarui access token dengan sendirinya sebelum kedaluwarsa. lg logout juga mengakhiri sesi di server, dan Anda dapat menghapusnya di panel melalui Settings › Integration keys › AI and CLI connections. lg login --password (email dan kata sandi) tetap tersedia sebagai cadangan. Memerlukan lg 0.11 atau yang lebih baru.
3. Untuk server dan CI: kunci, bukan kode persetujuan — Server atau job CI tidak memiliki siapa pun yang dapat menyetujui kode di browser. Terbitkan kunci di panel (Settings › Integration keys) atau dengan lg keys create — secara opsional atas nama anggota tim khusus dengan cakupan sempit — lalu taruh di LOGISTIVO_TOKEN, atau simpan dengan lg login --api-key. Selama variabel itu diset, file konfigurasi tidak pernah dibaca. Detail: bagian "Terhubung dengan kunci API".
4. Verifikasi dan jelajahi katalog — lg commands menampilkan setiap perintah yang dapat dilihat oleh peran Anda, dikelompokkan per domain; lg help mencetak verb dari domain tersebut, dan lg help mencetak daftar parameter lengkap satu perintah beserta tipenya dan mana yang wajib. Tidak satu pun teks itu berada di dalam klien — semuanya berasal dari katalog. Ingat bahwa daftar ini bergantung pada peran Anda: verb dari satu domain tidak sama untuk pengangkut dan untuk pengirim (loads set-status, misalnya, hanya ada di katalog pengangkut). Jika sebuah verb tidak ada, periksa peran Anda sebelum memeriksa instalasi Anda.
Jangan pernah menaruh kunci di version control, log CI, atau jendela chat. Jika Anda masuk dengan kode persetujuan atau kunci integrasi, lg logout juga mengakhirinya di server; pada sesi kata sandi (lg login --password), perintah itu hanya menghapus salinan LOKAL dan menyatakannya secara eksplisit. Log audit menyimpan argumen Anda, tetapi menyamarkan setiap field yang namanya mengandung token, password, IBAN, card, atau OTP sebagai ***, serta setiap parameter yang dinyatakan rahasia oleh sebuah perintah.
LOGISTIVO_TOKEN — Token akses pribadi. Selama variabel ini diset, file konfigurasi tidak pernah dibaca — inilah jalur yang disarankan di CI dan di server.
LOGISTIVO_BASE_URL — Root server. Bawaannya https://logistivo.com. Ubah hanya jika Anda mengarah ke lingkungan Anda sendiri; flag --base-url melakukan hal yang sama untuk satu perintah.
LOGISTIVO_HOME — Direktori untuk file konfigurasi dan cache katalog. Bawaannya ~/.logistivo. Pisahkan jika Anda bekerja dengan dua akun di satu mesin.
LOGISTIVO_PROFILE — Profil mana yang digunakan untuk menjalankan. `lg profile use` adalah pilihan yang persisten; variabel ini berlaku untuk satu kali eksekusi dan merupakan cara tersingkat untuk beralih antara profil live dan sandbox di CI. Nama profil yang tidak dikenal tidak diabaikan diam-diam — hasilnya error.
NO_COLOR — Jika diset, tidak ada warna ANSI yang dicetak (bentuk permanen dari flag `--no-color`). Aktifkan untuk jembatan (bridge) yang menulis ke file log atau output CI; escape sequence warna merusak tool yang kemudian membaca log tersebut.
Ergonomi klien
Fitur-fitur ini memudahkan penggunaan klien `lg` sehari-hari. Tidak satu pun yang mengubah kontrak HTTP — lewati bagian ini jika Anda berintegrasi langsung melalui HTTP.
Beberapa lingkungan dan kunci — Simpan staging dan produksi, atau jembatan pelanggan dan pengangkut Anda, dalam profil yang terpisah. Daftar profil tidak pernah mencetak token; setiap baris menampilkan sidik jari sha256 dari token tersebut. Katalog perintah di-cache per profil, host, dan token, sehingga dua peran tidak akan pernah melihat daftar perintah satu sama lain.
Sinkronisasi inkremental: lg sync — Menjalankan loop sinkronisasi dari cookbook dalam satu perintah: watermark per entitas, updated_since dengan cursor, output JSONL, dan margin keamanan lima menit. Gunakan --full untuk backfill pertama. Perintah ini hanya membaca; tidak ada flag --write. lg sync --list menurunkan daftar entitas yang dapat disinkronkan untuk peran Anda dari katalog.
Pengalaman error dan shell completion — Pada 422, klien menyebut field yang ditolak sebagai flag yang Anda ketik, beserta error_key yang stabil dan penjelasan katalog sendiri tentang key tersebut. Pada 409, klien mencetak baris perintah --yes yang siap pakai; pada 429, klien menunggu hingga Retry-After berlalu. Shell completion mencakup domain, verb, flag, dan nilai enum, serta berfungsi secara offline.
Parameter rahasia tidak pernah ditaruh di baris perintah — Beberapa perintah menerima secret — misalnya, menghubungkan integrasi akuntansi Paraşüt memerlukan client credentials dan kata sandi sistem tersebut. lg tidak pernah menerima nilai seperti itu sebagai flag, karena nilainya akan berakhir di riwayat shell dan di output ps: lg memintanya tanpa echo, atau membacanya dari ---file=PATH atau dari stdin (---file=-), dan hanya menyimpannya di memori. Perintah yang parameter wajibnya bersifat rahasia hanya dapat dijalankan dari lg: jika dipanggil dari chat, melalui MCP, atau di dalam lg batch, perintah itu ditolak dengan SECRET_REQUIRES_CLI. Log audit selalu mencatat nilainya sebagai ***.
Terhubung dengan kunci API
ERP, CRM, skrip, atau agen AI terhubung ke Logistivo dengan kunci integrasi yang diterbitkan di panel atau dengan lg keys create. Kunci bertindak atas nama anggota tim yang nyata: peran orang itu menentukan daftar perintah, tingkat akses kunci menentukan seberapa berat pekerjaan yang boleh dilakukan, dan ketika orang itu keluar dari tim, kuncinya ikut mati bersamanya. Tidak ada "akun layanan" sintetis dan tidak akan pernah ada — isolasi multi-tenant terikat pada pengguna, dan jembatan tanpa pemilik adalah jenis jembatan yang diam-diam terus menulis selama bertahun-tahun.
1. Terbitkan kunci di panel — Settings › Integration keys › New key. Beri nama ("ERP nightly sync"), pilih scope dan tingkat aksesnya, dan secara opsional persingkat masa berlakunya. Kunci ditampilkan satu kali, hanya di layar itu; server tidak menyimpannya. Jika Anda kehilangannya, Rotate akan menerbitkan kunci baru — kunci lama langsung menjadi tidak valid.
2. Hubungkan dari terminal — lg login --api-key memvalidasi kunci, mencetak identitas dan scope, lalu mengunduh katalog perintah. lg whoami menanyakan kepada server sebagai pengguna, perusahaan, peran, dan scope apa Anda sedang berjalan. lg logout juga mencabut kunci di server, sama seperti perintah itu mengakhiri sesi kode persetujuan di sana (hanya lg logout pada sesi kata sandi yang tidak dapat melakukan itu).
3. Atau HTTP biasa — Kunci adalah access token yang dibawa dalam header Authorization: Bearer dan berfungsi langsung terhadap ketiga endpoint perintah. Di server atau di CI, taruh kunci itu di LOGISTIVO_TOKEN; selama variabel itu diset, file konfigurasi tidak pernah dibaca.
4. Atau kelola kunci dari terminal: lg keys — lg keys adalah kembaran terminal dari layar panel: endpoint yang sama, gerbang yang sama (izin pengelolaan tim, dan kunci tingkat manager jika Anda memanggilnya dengan sebuah kunci). create, rotate, dan transfer mengembalikan token baru satu kali: dengan --save-profile=NAME, token langsung masuk ke profil lokal dan tidak pernah dicetak; jika tidak, lg mencetaknya satu kali. Dalam mode --json, token hanya disertakan jika Anda menambahkan --show-secret, dan panggilan --json tanpa salah satu dari kedua flag itu ditolak sebelum permintaan dikirim, sehingga token tidak dapat diam-diam masuk ke output skrip. rotate, transfer, dan revoke meminta konfirmasi (--yes); sebuah kunci dirujuk dengan nama persisnya atau uuid-nya, tidak pernah dengan tebakan. Tingkat akses terbawa tanpa perubahan ke kunci yang dirotasi atau ditransfer.
Scope ditegakkan di seluruh permukaan API, tidak hanya di katalog perintah: kunci read-only meloloskan permintaan baca (GET/HEAD/OPTIONS) dan setiap permintaan tulis lainnya menjawab 403 forbidden. Ada dua pengecualian yang disengaja dan keduanya dijaga oleh gerbang yang lebih halus: endpoint eksekusi perintah (keputusan diambil dari penanda read_only milik perintah itu sendiri, karena perintah yang tidak menulis juga dipanggil dengan POST) dan kunci yang mencabut dirinya sendiri (lg logout, juga diizinkan pada kunci read-only). Scope, pemberian akses domain, dan tingkat akses adalah tiga sumbu yang independen dan semuanya harus lolos: kunci read tidak dapat menulis bahkan pada tingkat manager, kunci write tingkat employee tidak dapat mengelola tim, dan pemberian akses domain loads:write tidak membuka pekerjaan manajemen. Terbitkan kunci atas nama anggota dengan hak paling sedikit yang mencukupi kebutuhan Anda: peran menentukan rekaman mana yang dapat Anda lihat sama sekali.
read — Katalog perintah dan perintah yang tidak menulis (list, search, preview). Perintah tulis mengembalikan 403 forbidden — sebelum gerbang konfirmasi; kunci read-only bahkan tidak pernah melihat 409. Pilihan yang tepat untuk sinkronisasi malam hari dan pelaporan.
write — Setiap perintah. Perintah yang memerlukan konfirmasi tetap memintanya dengan 409; confirm: true (--yes di CLI) berfungsi persis seperti sebelumnya. Scope tidak pernah melonggarkan gerbang konfirmasi.
employee — Bawaan untuk setiap kunci baru. Operasi sehari-hari: muatan, permintaan angkutan, penawaran, perjalanan, armada dan dokumen armada, dokumen, kontak — setiap perintah yang tidak memerlukan izin manajemen, ditambah izin armada. Perintah yang memerlukan lebih dari itu menjawab 422 dengan error_key INSUFFICIENT_KEY_LEVEL dan required_key_level: manager; endpoint REST yang sesuai menjawab 403 dengan key yang sama. Tingkat yang tepat untuk sinkronisasi malam hari ERP, jembatan telematika, atau skrip operasional.
manager — Semua hal yang boleh dilakukan oleh orang yang diwakili kunci, termasuk manajemen: anggota tim dan peran, pengaturan perusahaan, kunci integrasi, rekening bank dan verifikasinya, kartu tersimpan, hubungan antarperusahaan, pembayaran afiliasi. Kunci manager tidak pernah menambahkan hak yang tidak dimiliki orang tersebut — tanpa izin pengelolaan tim, kunci itu tetap tidak dapat mengelola tim. Kunci yang sudah ada sebelum tingkat akses diperkenalkan adalah kunci manager, sehingga perilakunya persis seperti sebelumnya.
Satu kunci per integrasi — Jika CRM dan ERP berbagi satu kunci, memutus salah satunya berarti memutus yang lain. Berikan setiap jembatan kuncinya sendiri; daftar kunci toh menampilkannya berdasarkan nama.
Rotasi — Menerbitkan token baru dan langsung mencabut token lama; sisa masa berlakunya dipertahankan. Gunakan saat ada dugaan kebocoran dan secara berkala. Integrasi akan mendapat 401 sampai diperbarui dengan token baru.
Pencabutan — Kunci ditutup secara permanen; hal ini tidak dapat dibatalkan, terbitkan kunci baru jika diperlukan. Jika anggota yang diwakili kunci dikeluarkan dari tim atau dinonaktifkan, kunci itu gugur dengan sendirinya.
Masa berlaku dan batas — Masa berlaku bawaan adalah 180 hari; Anda dapat mempersingkatnya saat membuat kunci, tetapi tidak pernah memperpanjangnya. Seorang pengguna dapat memegang paling banyak 10 kunci aktif. Waktu penggunaan terakhir terlihat di daftar; kunci yang belum pernah digunakan menyatakannya secara eksplisit.
Siapa yang mengelola — Menerbitkan, merotasi, mentransfer, dan mencabut kunci terbuka bagi manager yang memiliki izin pengelolaan tim — gerbang yang sama dengan menambah atau menghapus anggota tim — dan, jika dilakukan dengan kunci integrasi, kunci tersebut harus bertingkat manager. Seorang manager dapat menerbitkan kunci atas nama anggota lain; untuk sebuah jembatan, disarankan anggota khusus dengan cakupan sempit.
Sepuluh menit pertama: dari panel ke panggilan pertama Anda
Menit-menit paling mahal dalam sebuah integrasi adalah sepuluh menit pertama. Empat langkah di bawah ini menguraikan jalur tersebut secara berurutan; urutan yang sama tersedia di panel sebagai wizard (Settings › Integration › Setup wizard), dan wizard itu memanggil persis endpoint yang dijelaskan di sini. Pengembang yang tidak memiliki akses ke wizard mencapai tempat yang sama dengan membaca bagian ini.
Tidak satu pun dari keempat langkah itu berakhir dengan "saya sudah mengirimnya". Apakah kunci benar-benar berfungsi dijawab oleh ledger permintaan; apakah webhook benar-benar sampai dijawab oleh ledger pengiriman. Keduanya terbuka di panel dan di lg. Penyiapan yang tidak pernah diukur adalah penyiapan yang hanya dipercaya berfungsi.
1. Tentukan apa yang akan Anda lakukan — tetapkan scope terlebih dahulu — Tidak ada kesempatan untuk memutuskan belakangan apa yang boleh dilihat oleh sebuah kunci: Anda memilih scope saat menerbitkannya. Ada dua sumbu. Scope kasar (read / write) hanya menjawab "apakah kunci ini boleh menulis". Scope halus (pemberian akses domain: loads:read, invoices:write) menyatakan domain mana yang boleh disentuhnya, dan begitu diatur, kunci menjadi fail-closed — setiap domain yang tidak Anda pilih, dan setiap endpoint yang tidak terpetakan ke domain mana pun, mengembalikan 403. Daftar domain di panel bukanlah daftar yang ditulis tangan; daftar itu diturunkan dari katalog perintah peran Anda yang aktif dan menunjukkan berapa banyak perintah dan endpoint REST yang dibuka oleh setiap domain. Endpoint katalog perintah, "siapa saya" (current), dan "keluar" selalu dikecualikan dari scope: sebuah kunci harus selalu dapat mendeskripsikan dan menutup dirinya sendiri. Sumbu ketiga adalah tingkat akses: employee (bawaan) menjalankan operasi sehari-hari, manager juga mengerjakan urusan tim, pengaturan, kunci, dan uang. Pilih employee kecuali jembatan Anda melakukan pekerjaan manajemen.
2. Terbitkan kunci — token ditampilkan satu kali — Settings › Integration › New key. Beri nama ("ERP nightly sync"), pilih pengguna yang diwakilinya dan tingkat aksesnya, lalu persingkat masa berlakunya jika Anda mau. Token mentah hanya dikembalikan dalam respons itu; server tidak menyimpannya dan tidak ada "tampilkan lagi" di panel. Jika hilang, lakukan rotasi untuk mendapatkan token baru dan token lama langsung mati. Jangan pernah menaruh token di version control, log CI, atau jendela chat; taruh di penyimpanan secret sistem tujuan.
3. Lakukan panggilan pertama — dan pastikan panggilan itu BENAR-BENAR sampai — Dua permintaan sudah cukup. Yang pertama membuktikan identitas Anda (dikecualikan dari scope dan berfungsi dengan setiap kunci): apakah scope-nya sesuai harapan Anda, apakah statusnya aktif, apakah expires_at sudah dekat. Yang kedua membaca data sungguhan dari domain yang Anda pilih. Jika lolos, identitas, scope, gerbang e-mail, dan jalur jaringan semuanya benar. Jika tidak, jangan menebak: ledger permintaan milik kunci itu sendiri menunjukkan, baris demi baris, endpoint mana yang ditolak dengan kode apa dan key error stabil apa (INSUFFICIENT_SCOPE, IP_NOT_ALLOWED, KEY_ACTOR_BLOCKED …). Di panel, ledger itu adalah jendela "Recent requests"; di terminal, itu adalah lg logs. Wizard mengamati tepat ledger ini dan menolak menandai langkah itu hijau sampai melihat panggilan sungguhan yang berhasil.
4. Siapkan webhook — dan verifikasi tanda tangan sebelum melakukan apa pun — Menunggu event lebih murah daripada bertanya setiap menit. Daftarkan alamat https, pilih event yang Anda pedulikan, dan ikat langganan ke kunci Anda: jika kunci dicabut, pengiriman juga berhenti. Secret hanya ditampilkan satu kali, saat dibuat. Endpoint penerima Anda harus memverifikasi tanda tangan terlebih dahulu: string yang ditandatangani adalah "{t}.{raw body}" dan algoritmanya HMAC-SHA256; timestamp berada DI DALAM tanda tangan, jadi buang setiap permintaan yang lebih tua dari 300 detik meskipun tanda tangannya valid. Bandingkan dalam waktu konstan dan jangan pernah menserialisasi ulang body — begitu Anda mem-parsing JSON dan mencetaknya lagi, tanda tangannya tidak lagi cocok. Dari panel, "Send test" memicu ping bertanda tangan yang sungguhan dan Anda dapat mengamati pengirimannya percobaan demi percobaan.
Sandbox: berlatih menulis tanpa menyentuh produksi
Preflight (dry_run) memberi tahu Anda apa yang AKAN dilakukan sebuah perintah; tetapi apakah idempotency benar-benar memutar ulang, apakah webhook benar-benar terkirim, seperti apa cabang-cabang error-nya, dan dari mana kredit diambil hanya dapat dilihat dalam penulisan SUNGGUHAN. Untuk itulah sandbox ada: tenant terpisah yang mencerminkan perusahaan Anda — kode yang sama, katalog perintah yang sama — dan tidak pernah menyentuh ledger live Anda.
Sandbox bukan penanda permintaan, melainkan sebuah TENANT. Perusahaan Logistivo terpisah yang dibuka untuk perusahaan Anda: dengan pengguna sendiri, paket sendiri, ledger kredit sendiri, dan langganan webhook sendiri. Lingkungan DITURUNKAN dari perusahaan pemilik kunci dan tidak dapat diberikan oleh pemanggil, sehingga meskipun Anda memilih profil yang salah, permintaan akan berhenti di sisi server dengan 403 ENVIRONMENT_MISMATCH. "Saya kira saya menulis ke sandbox, ternyata menulis ke produksi" secara struktural tidak mungkin terjadi.
Permukaannya identik — terukur: katalog yang diperoleh kunci sandbox sama dengan yang diperoleh kunci live Anda (pada kunci pengirim, 646 perintah di kedua sisi). Jembatan yang berfungsi di sandbox juga berfungsi di produksi; tidak ada yang perlu Anda pelajari dua kali.
Sandbox tidak dibuka dalam keadaan kosong: sandbox berisi data awal yang dihasilkan (BUKAN disalin) — kontak, muatan di kedua arah, dan permintaan angkutan. Nama-namanya terang-terangan rekaan dan alamat e-mail-nya berada di domain @sandbox.invalid; tidak ada baris milik tenant sungguhan yang pernah dibaca, dikloning, atau dipakai sebagai templat.
Sengaja TIDAK ada tombol reset, dan tidak ada rekaman, file, atau dokumen yang pernah dihapus. Jika Anda menginginkan awal yang bersih, pembaruan membuka generasi baru dan generasi lama tetap ada dalam keadaan pensiun. Beberapa ratus baris latihan yang menumpuk tidak ada artinya dibandingkan rutinitas penghapusan yang tersambung ke tenant yang salah.
1. Buka sandbox — Satu sandbox per perusahaan. Endpoint ini memerlukan izin pengelolaan tim (team.manage), sehingga seorang administrator di perusahaan Anda yang melakukannya. Jika sandbox sudah ada, endpoint yang sama menjawab melalui GET dengan keadaannya: id perusahaan, sisa kredit, jumlah kunci aktif, langganan, riwayat generasi, dan batas atasnya.
2. Terbitkan kunci sandbox dan simpan sebagai profil kedua — Kunci diterbitkan atas nama pengguna jembatan milik sandbox itu sendiri dan dikembalikan dengan stempel environment: sandbox; token mentah hanya muncul dalam satu respons itu. Di sisi lg, jangan mengganti kunci live Anda — simpan KEDUANYA sebagai profil terpisah; --sandbox dan --live adalah pemilih untuk satu kali eksekusi.
3. Lakukan penulisan sungguhan — Tidak ada --dry-run di sini; menulis adalah inti dari semuanya. Kirim idempotency key yang sama dua kali dan lihat respons kedua kembali sebagai status: replayed — itulah hasil terukur di sandbox. Panggil perintah yang dijaga gerbang tanpa konfirmasi secara sengaja dan baca body 409-nya; coba perintah di luar scope Anda dan baca penolakannya. Tidak satu pun meninggalkan jejak di ledger live Anda: saldo live Anda tidak berubah selama eksekusi yang sama.
4. Baca daftar periksa sebelum go-live — Endpoint go-live menjawab berdasarkan apa yang BENAR-BENAR Anda lakukan di sandbox: apakah Anda menulis, apakah Anda melihat cabang-cabang error, apakah ada webhook yang terkirim, apakah Anda memindahkan penerima dari alamat latihan, apakah Anda menetapkan masa berlaku pada kunci. Setiap item dikembalikan sebagai pass / todo / unknown. Respons yang sama juga membawa USULAN SCOPE yang diturunkan dari perintah yang benar-benar Anda panggil — gunakan usulan itu untuk menerbitkan kunci live Anda tanpa melebihi kebutuhan Anda.
Kredit dan penagihan — Sandbox memiliki ledger kreditnya sendiri dan saldo live Anda tidak bergerak. Itu adalah struktur, bukan pemeriksaan: kredit dihitung per perusahaan dan sandbox adalah perusahaan yang terpisah. Sandbox dibuka pada tingkat gratis, tidak memiliki metode pembayaran, dan berada di luar jendela penagihan bulanan — sandbox tidak dapat mencapai faktur melalui jalur apa pun.
Marketplace — Permintaan angkutan yang Anda buka di sandbox TIDAK muncul di layar pengangkut sungguhan dan TIDAK sampai ke kotak masuk e-mail atau push mereka; dan Anda juga tidak melihat permintaan angkutan sungguhan. Pemisahan ini simetris dan ditegakkan dalam dua kueri terpisah: kepada siapa sebuah permintaan angkutan TERLIHAT dan kepada siapa permintaan itu DIKIRIM adalah pertanyaan yang berbeda.
Webhook — Langganan juga membawa stempel lingkungan. Event sandbox tidak pernah dikirim ke langganan live dan event live tidak pernah sampai ke langganan sandbox; untuk langganan yang stempelnya sudah bergeser, tidak ada pengiriman yang dibuka sama sekali. Karena batas atas langganan berlaku per perusahaan, langganan latihan Anda tidak menghabiskan kuota live Anda.
Data awal — Contoh rekaman di dalam sandbox DIHASILKAN, tidak pernah disalin dari tenant sungguhan. Pengisian data awal bersifat idempoten: panggilan kedua tidak menumpuk data awal kedua di atas rekaman Anda sendiri.
Katalog yang sama — Peran Anda di sandbox tetap peran Anda, dan daftar perintahnya identik — terukur, 646 perintah di kedua sisi. Sandbox bukan demo yang dipangkas; sandbox adalah kembaran perusahaan Anda.
Batasan saat ini: langganan webhook tidak dapat dikelola dengan kunci sandbox — Endpoint langganan memerlukan izin pengelolaan tim (team.manage), dan pengguna jembatan milik sandbox tidak membawa peran tim, sehingga `lg --sandbox webhooks …` saat ini menjawab 403. Seluruh permukaan perintah berfungsi — pembatasan hanya berlaku pada ledger langganan. Jika Anda ingin melatih webhook di sandbox, hubungi dukungan; hal ini sudah diukur dan dicatat sebagai celah yang masih terbuka.
GET /api/common/integration-sandbox — Keadaan: apakah sandbox ada, perusahaan mana, sisa kredit, jumlah kunci aktif dan langganan, riwayat generasi, batas atas, serta panduan pemicu yang menunjukkan perintah mana yang memunculkan event mana.
POST /api/common/integration-sandbox — Membuka sandbox (satu per perusahaan, idempoten). Memerlukan izin team.manage.
POST /api/common/integration-sandbox/keys — 201 + kunci dan token mentah (hanya di sini, hanya satu kali). Stempel environment: sandbox diturunkan dari perusahaan; pemanggil tidak dapat memberikannya.
GET /api/common/integration-sandbox/go-live — Daftar periksa go-live dan usulan scope — dihitung dari lalu lintas sungguhan Anda di sandbox.
POST /api/common/integration-sandbox/renew — Membuka GENERASI sandbox baru dan memensiunkan generasi sebelumnya.
Model perintah
Hanya ada satu tata bahasa dan tidak ada pengecualian. Untuk mengetahui cara memanggil sebuah perintah, satu-satunya yang Anda butuhkan adalah apa yang dikatakan katalog tentang perintah itu.
lg loads list --status=in_transport --limit=20 --json
Nama flag adalah nama parameter dalam schema, dan lg menerima kedua ejaan: --load_code dan --load-code mencapai field yang sama (lg help mencetak bentuk kebab-case). Jadi, dengan melihat sebuah flag Anda langsung tahu ke field JSON mana nilainya masuk, dan berpindah dari CLI ke HTTP tidak memerlukan penerjemahan nama. Parameter boolean yang ditulis tanpa nilai bernilai true (--only_open); kebalikannya adalah --no-only_open. Tulis argumen yang nilainya diawali tanda hubung sebagai --flag=value; jika tidak, flag yang lupa diberi nilai akan diam-diam menelan flag berikutnya sebagai nilainya. Pada perintah yang menerima file, tambahkan @ di depan path lokal (--attachment_uuid=@./cmr.pdf) — lihat Perintah yang menerima file.
lg — Klien.
loads — Domain — entitas yang sedang Anda kerjakan, dalam bentuk jamak.
list — Verb — apa yang Anda lakukan terhadap entitas itu, diambil dari kosakata tertutup yang hanya bertambah melalui keputusan yang disengaja: verb sederhana (list, get, create, update, delete, search, preview, generate, extract …) dan verb majemuk yang menyebut apa yang dilampirkan atau diubah (add-document, set-status, assign-driver). lg help menampilkan verb sebuah domain.
--status=in_transport — Parameter — namanya persis sama dengan nama parameter di JSON Schema dan nilainya harus sesuai dengan tipe dalam schema. Nilai yang tidak valid pada field enum tidak pernah sampai ke server.
--limit=20 — Jumlah baris pada perintah daftar. Batas atasnya tercantum dalam deskripsi parameter setiap perintah — biasanya 20 pada panggilan list biasa dan hingga 100 dalam mode sinkronisasi (dengan cursor atau updated_since).
--json — Output JSON mentah.
--json — Mencetak JSON mentah. Inilah satu-satunya bentuk yang benar untuk skrip: tabel rata bawaan ditujukan untuk manusia, memilih kolomnya dari data, dan dapat mengubah tata letaknya tanpa pemberitahuan. Jangan pernah menulis skrip yang mem-parsing output tabel.
--yes, -y — Melewati gerbang konfirmasi (confirm: true melalui HTTP). Gunakan hanya dalam skrip yang tahu apa yang akan dilakukannya; pada perintah yang tidak dapat dibatalkan, flag ini adalah singkatan dari "tidak ada undo".
--idempotency-key= — Membuat percobaan ulang perintah tulis menjadi aman. Panggilan kedua dengan kunci yang sama tidak menjalankan ulang perintah; panggilan itu mengembalikan hasil pertama. Jika Anda membangun loop percobaan ulang, buat kuncinya SENDIRI dan kirim kunci yang sama pada setiap percobaan.
--dry-run — Menjalankan preflight alih-alih perintahnya: validasi, gerbang, dan perhitungan kredit dijalankan, tidak ada yang ditulis (lihat bagian preflight). Berlaku pada setiap perintah dan pada lg batch.
--refresh — Memaksa penyegaran katalog. lg menyimpan katalog di cache selama satu jam; jika Anda tahu sebuah perintah baru saja ditambahkan di server, gunakan ini alih-alih menunggu.
--help, -h — Mencetak deskripsi katalog dari perintah, setiap parameter, tipenya, nilai enum-nya, dan apakah parameter itu wajib. Tidak ada file bantuan di dalam klien.
--profile=, --sandbox, --live — Profil mana yang digunakan untuk satu panggilan ini. --sandbox dan --live memilih profil yang memegang kunci sandbox atau kunci live; lingkungan ditentukan dari kunci di server, sehingga ketidakcocokan akan berhenti dengan 403 ENVIRONMENT_MISMATCH alih-alih menulis ke tempat yang salah.
--base-url, --timeout, --verbose, --no-color, --version — Berturut-turut: mengarahkan satu perintah ke server lain, batas waktu dalam detik, detail permintaan/respons, menonaktifkan warna ANSI, dan versi klien.
Contoh nyata
Setiap perintah di bawah ini ada di katalog hari ini; tidak ada nama atau parameter yang dikarang di sini. Output dipersingkat. Output menampilkan tingkat `data.result`; melalui HTTP, objek yang sama tiba di dalam envelope `{success, data:{…}}` (lihat API perintah HTTP).
Muatan yang sedang dalam perjalanan — lg loads list --status=in_transport --limit=20
Satu muatan secara lengkap, JSON mentah — lg loads get --load_code=FSK2158 --json
Penanda konsistensi dokumen yang masih terbuka — lg loads list-problems --only_open=true --limit=10
Tentukan negaranya — lg countries search --query=Germany --json
Filter dengan id yang sudah ditemukan — lg loads list --receiving_country_id=57 --date_from=2026-09-01 --limit=20
Temukan kode HS dari nama produk — lg tariffs search --query="aluminium profile"
Majukan status sebuah muatan (hanya peran pengangkut) — lg loads set-status --load_code=FSK2158 --status=transit --date=2026-08-21 --yes
Draf — lg export-documents create --doc_type=proforma-invoice --currency_code=EUR --json
Hasilkan dokumennya (dijaga gerbang) — lg export-documents generate --document_id=8412 --yes
Tanpa klien: API perintah HTTP
lg adalah kemudahan, bukan satu-satunya pintu. Katalog dan eksekusi sama-sama melewati tiga endpoint HTTP (untuk file ada endpoint keempat, yaitu endpoint unggah — lihat Perintah yang menerima file); integrasi ERP atau CRM terhubung langsung ke sini. Identitas berupa personal access token yang dibawa dalam Authorization: Bearer. SETIAP respons kembali dalam envelope yang sama: `{ "success": bool, "data": { … }, "code": "…", "message": { … } }`. Seluruh kontrak berada di dalam `data` — `contract_version`, `command`, `status` dan, sebagai output perintah, `result`; jika gagal, `error_code`, `error_key`, dan `error`. Contoh respons di halaman ini menampilkan objek `data`, bukan envelope-nya, untuk menghemat tempat; jangan lupa membuka `data` di kode Anda sendiri. `lg --json` juga mencetak envelope SECARA UTUH, itulah sebabnya path jq diawali dengan `.data.result…`. Satu-satunya pengecualian adalah `/api/public/status`: endpoint itu tidak memakai envelope agar watchdog dapat memberi peringatan tanpa perlu mem-parsing-nya.
Meminta konfirmasi dengan 200 + ok:false dilarang dan tidak akan pernah terjadi. Alasannya sederhana: klien menganggap 200 sebagai sukses, sehingga permintaan konfirmasi yang dikembalikan sebagai 200 akan mematikan alur secara diam-diam dan tidak ada yang menyadarinya. Konfirmasi selalu 409.
GET /api/common/commands — Seluruh katalog yang dapat dilihat oleh peran Anda: contract_version; per perintah: name, domain, verb, description, JSON Schema, read_only, confirmation_needed, irreversible, credit_cost, since, deprecated_at, replaced_by, aliases, serta field akses key_level, permission, file_params, secret_parameters, dan cli_only; di tingkat teratas: kamus error_keys, rate_limits, idempotency_ttl_hours, peran katalog Anda, kontrak attachments (unggah), dan tingkat akses kunci yang Anda gunakan untuk memanggil. Mengirim ETag; If-None-Match menjawab 304. ?domain= juga cocok dengan domain lama (alias). Bangun klien Anda dari endpoint ini; jangan menulis daftar perintah secara hard-code.
GET /api/common/commands/{name} — Satu perintah secara lengkap. name adalah nama perintah yang dibekukan dari katalog (list_loads), bukan identitas CLI. Perintah yang sudah usang menjawab dengan header X-Deprecated.
POST /api/common/commands/{name} — Eksekusi. Body: { args, confirm?, idempotency_key? }. Status HTTP dari respons adalah hasil itu sendiri — apa pun selain 200 adalah informasi, bukan gangguan. Error membawa error_code (transport) dan, untuk penolakan bisnis, error_key.
Perintah yang menerima file
38 perintah di tabel menerima dokumen atau foto: melampirkan CMR ke sebuah muatan, membaca kode HS dari faktur, membuat kendaraan dari dokumen registrasinya, memperkirakan palet dari foto, mengunggah dokumen perusahaan, mencocokkan faktur dengan packing list. Di browser, Anda cukup menjatuhkan file ke dalam formulir; di tempat lain, prosesnya dua langkah — unggah file, lalu teruskan id-nya ke perintah.
Sebuah parameter menerima file jika namanya diakhiri dengan attachment_uuid atau attachment_uuids — photos[].attachment_uuid di dalam daftar, front_attachment_uuid pada cek. Anda tidak perlu mengingatnya: setiap baris katalog membawa file_params dengan path yang persis, schema menandai field tersebut (format: uuid, x-logistivo-file: true), dan respons katalog membawa blok attachments dengan alamat unggah, tipe yang diterima, batas ukuran, dan masa berlaku. lg help juga menampilkannya.
Mengunggah adalah penulisan, sehingga kunci dengan scope baca tidak dapat mengunggah; setiap kunci dengan scope tulis dapat melakukannya, pada tingkat akses mana pun. Unggahan adalah milik pengguna, bukan milik kunci: dua kunci dari pengguna yang sama melihat unggahan yang sama, dan tidak ada yang dapat menggunakan unggahan milik orang lain. Id yang tidak dikenal, sudah kedaluwarsa, atau bukan milik Anda dianggap tidak ditemukan, dan alasannya tidak diungkapkan.
Lampiran chat dashboard dan unggahan perintah adalah ruang yang terpisah: file yang dilampirkan di chat asisten tidak dapat diteruskan ke perintah berdasarkan id, dan unggahan perintah tidak pernah muncul di thread chat.
Unggahan bukanlah perintah dan tidak memiliki efek bisnis dengan sendirinya: tidak ada yang terjadi pada data Anda sampai sebuah perintah menggunakan id tersebut. Itulah juga sebabnya mengunggah tidak pernah meminta konfirmasi — perintah yang menggunakan file itulah yang membawa gerbangnya.
1. lg: tambahkan @ di depan path lokal — lg mengunggah file terlebih dahulu, lalu menjalankan perintah dengan id yang dikembalikan; nilai tanpa @ adalah id file yang sudah Anda unggah sebelumnya. Daftar menerima path yang dipisahkan koma atau flag yang diulang, field bersarang menerima JSON, dan --file adalah jalan pintas ketika perintah memiliki tepat satu field file di tingkat teratas. lg memverifikasi setiap file secara lokal (keberadaan, ukuran, tipe) sebelum apa pun dikirim, dan lg batch mengunggah setiap file yang berbeda satu kali sebelum batch dijalankan.
2. HTTP: unggah, lalu teruskan attachment_uuid — Kirim file sebagai multipart/form-data dalam field bernama file. Unggahan baru menjawab 201; file yang sama yang diunggah lagi oleh pengguna yang sama menjawab 200 dengan status replayed dan id yang sama, dan tidak ada yang ditulis. Seperti di bagian lain halaman ini, contohnya menampilkan objek data di dalam envelope.
3. MCP: tool upload_attachment — Klien MCP tidak dapat mengirim multipart, sehingga kanal ini menyediakan satu tool tambahan yang tidak ada di katalog: upload_attachment menerima nama file dan isinya dalam base64, lalu mengembalikan attachment_uuid yang sama. Tool ini memanggil layanan yang sama dengan unggahan HTTP, di bawah aturan yang sama.
Tipe ditentukan dari isi — Nama file dan tipe yang dideklarasikan diabaikan; ekstensi yang disimpan adalah ekstensi hasil deteksi. Diterima untuk diunggah: jpg, jpeg, png, webp, heic, heif, pdf, xlsx, xls, csv, txt, doc, docx, xml, zip. Setiap perintah kemudian menerapkan daftarnya sendiri yang lebih sempit sebelum apa pun dijalankan, dan menjawab UNSUPPORTED_FILE_TYPE beserta tipe yang diterima, atau FILE_TOO_LARGE.
Ukuran — Gambar hingga 10 MB, file lain hingga 15 MB.
Masa berlaku — Sebuah unggahan dapat digunakan selama 24 jam. Setelah itu, unggahan tidak lagi di-resolve (ATTACHMENT_NOT_FOUND) — unggahan itu tidak dihapus. Unggah lagi jika sebuah perintah gagal karena alasan tersebut.
File yang sama, id yang sama — Mengunggah file yang sama sekali lagi (nama, ukuran, dan isi yang sama) mengembalikan id yang sudah ada alih-alih menulis yang baru, selama sisa masa berlakunya paling sedikit satu jam, dan tidak mengurangi batas atas harian Anda.
Batas atas harian — 300 unggahan per pengguna per hari (TOO_MANY_FILES) dan 2 GB per perusahaan per hari (DAILY_LIMIT_REACHED); keduanya menjawab 429 dengan retry_after.
POST /api/common/commands:upload — Unggahan multipart dalam field file. 201 untuk unggahan baru, 200 dengan status replayed untuk file yang sama. Mengembalikan data.attachment: attachment_uuid, filename, mime_type, size_bytes, sha256, extraction_status, expires_at, dan reused.
Gerbang konfirmasi dan perintah yang tidak dapat dibatalkan
Setiap perintah di katalog membawa dua penanda: confirmation_needed (apakah perintah itu memerlukan persetujuan eksplisit sebelum berjalan) dan irreversible (apakah efeknya dapat dibatalkan). Keduanya adalah pertanyaan yang terpisah, dan keduanya ditegakkan di server, bukan diserahkan pada sopan santun klien.
Gerbang ini menyangkut tanggung jawab, bukan aturan bisnis. Mengajukan penawaran adalah langkah pertama menuju kontrak angkutan; menerbitkan faktur menciptakan entri akuntansi; pergerakan stok mengubah sebuah buku besar. Tidak satu pun dari hal-hal ini boleh menjadi sesuatu yang dapat Anda jalankan dua kali secara tidak sengaja.
Gerbang dibaca dari perintah yang EFEKTIF. Ketika satu perintah membungkus perintah lain — seperti yang dilakukan executor generik di chat — gerbang diambil dari penanda milik perintah yang benar-benar akan berjalan, bukan dari pembungkusnya. Dengan penanda yang tetap, salah satu dari dua kegagalan tidak akan terhindarkan: perintah faktur berjalan tanpa konfirmasi, atau setiap pencarian negara memunculkan kartu konfirmasi.
read_only dan tanpa gerbang bukanlah hal yang sama. Ada tiga keadaan yang berbeda: invoices preview tidak dijaga gerbang dan tidak menulis apa pun; loads create dijaga gerbang dan menulis; invoices create tidak dijaga gerbang tetapi menulis — sebuah draf tercipta. Satu uji menentukannya: ketika perintah selesai, apakah ada baris di database yang berubah?
Beberapa tindakan tidak berada di balik gerbang ini karena memang sama sekali bukan perintah: membeli paket, menambahkan kartu dengan 3D Secure, menyetujui teks hukum, dan menutup akun terjadi di browser milik orang itu sendiri. Untuk tindakan-tindakan tersebut, lg handoff-links generate mengembalikan tautan logistivo.com — gratis, tidak menulis apa pun, tidak membawa secret — dan orang itu menyelesaikan langkahnya di sana. Tidak ada flag, bagaimanapun disetelnya, yang mengubah pembayaran atau persetujuan menjadi panggilan API.
Secara teknis, sebuah integrasi dapat melewati gerbang secara otomatis pada setiap panggilan, tetapi hal itu tidak disarankan. Pola yang benar adalah mengotomatiskan gerbang hanya untuk perintah yang Anda ketahui dapat dibatalkan, dan mengarahkan perintah yang tidak dapat dibatalkan ke antrean manusia.
1. Panggil — Panggil perintah yang dijaga gerbang tanpa confirm. Tidak ada yang berubah.
2. Baca ringkasannya — Anda mendapat 409; confirmation.summary di body adalah kalimat yang ditulis untuk manusia ("About to issue an invoice: X Ltd, 1,200.00 TRY"), bukan tumpahan argumen mentah. Perintah yang menyangkut uang juga membawa pratinjau terstruktur: baris item, total, peringatan.
3. Konfirmasi — Ulangi panggilan yang sama dengan confirm: true (--yes di CLI). Perintah yang tidak dapat dibatalkan ditandai sehingga dijalankan paling banyak satu kali.
Preflight: lihat apa yang akan dilakukan perintah tulis, tanpa menjalankannya
Langkah paling mahal dalam menyambungkan jembatan ERP adalah mencari tahu apakah body Anda sudah benar dengan BENAR-BENAR menjalankan perintahnya: draf faktur di buku besar yang aktif, kredit yang terbakar, pembersihan manual. dry_run mengakhiri hal itu — Anda menambahkan satu field ke permintaan, perintah tidak dijalankan, dan Anda membaca apa yang akan terjadi.
Registri saat ini memuat 721 perintah; 327 di antaranya hanya membaca dan tidak menulis apa pun. Dari 394 perintah tulis sisanya, 346 dijaga gerbang: jika dipanggil tanpa confirm, perintah-perintah itu sudah menjawab 409 dan menjelaskan apa yang akan dilakukannya. Celahnya ada pada 48 sisanya — draf faktur, draf dokumen ekspor, baris item: tepat rantai yang pertama kali disambungkan oleh sebuah jembatan. Untuk perintah-perintah itu, memanggil berarti mengeksekusi.
Ada celah kedua bahkan pada perintah yang dijaga gerbang: validasi schema berjalan SETELAH gerbang. Jadi, panggilan dengan argumen yang kurang mendapat kartu konfirmasi lebih dulu, mengonfirmasinya, dan baru kemudian mendengar "field ini tidak ada". Preflight menjawab keduanya dalam satu kali bolak-balik.
Dan bug jembatan yang paling umum — sekaligus yang paling terlambat ditemukan — adalah ini: Anda mengirim field yang tidak ada dalam schema (customer_id padahal yang diharapkan recipient_contact_id), server diam-diam membuangnya, perintah mengembalikan 200, dan rekaman berakhir di tempat yang salah. Respons preflight mencantumkan field-field itu berdasarkan nama di bawah arguments.ignored; tidak ada pesan error yang akan pernah melakukannya.
Preflight tidak menulis apa pun, dan hal itu bersifat struktural sebelum menjadi hasil pengukuran: jalur preflight tidak pernah masuk ke handler perintah, sehingga berlaku untuk setiap perintah, termasuk yang ditambahkan kemudian. Hal ini juga diukur saat fitur dirilis: setiap pernyataan SQL yang dijalankan selama preflight terhadap setiap perintah tulis di katalog saat itu (dua set argumen, dua peran, 178 preflight) direkam. Tidak ada satu pun INSERT/UPDATE/DELETE, tidak ada satu pun job dalam antrean, tidak ada satu pun email; jumlah baris di 31 tabel dan saldo kredit tidak berubah.
Kode keluarnya sama dengan yang akan dihasilkan oleh panggilan sungguhan — akan berjalan 0, gerbang konfirmasi 4, konflik idempotency 2, selain itu 1 — sehingga "lg … --dry-run || exit" merupakan gerbang yang bermakna dalam langkah CI.
1. Panggil dengan dry_run — Tambahkan "dry_run": true ke body permintaan. Validasi, gerbang peran dan scope, resolusi target, serta perhitungan kredit semuanya berjalan; perintahnya sendiri tidak.
2. Baca would_execute — Itulah satu-satunya penanda yang menjadi dasar percabangan. Jika nilainya false, would_stop.at menyebutkan di mana panggilan sungguhan akan berhenti: idempotency, target_precheck, confirmation_gate, atau arguments.
3. Perbaiki body Anda — arguments.ignored menyebutkan field yang akan dibuang diam-diam, missing_required menyebutkan field wajib yang Anda lewatkan, dan would_charge menyebutkan berapa kredit yang akan terpakai serta apakah saldonya mencukupi.
4. Hapus dry_run — Ulangi hingga would_execute bernilai true, lalu hapus penanda itu dan lakukan panggilan sungguhan. Idempotency key yang Anda kirim selama preflight tidak dikonsumsi, sehingga panggilan sungguhan berjalan secara normal.
HTTP selalu 200 — "Perintah ini akan gagal" tidak pernah datang sebagai 4xx — preflight itu sendiri berhasil dan prediksinya ada di body. Pengecualiannya adalah penolakan di tingkat transport, dan di sana perilakunya persis seperti panggilan sungguhan: 404 perintah tidak dikenal, 403 peran/scope, 429 rate limit.
Kunci dengan scope baca tidak dapat menjalankan dry run untuk perintah tulis — Kunci itu mendapat 403. Preflight menjawab "apa yang terjadi jika saya memanggil ini DENGAN KUNCI INI, sekarang"; memberi kunci baca lampu hijau lalu 403 pada panggilan sungguhan justru merupakan kejutan yang ingin dicegah oleh preflight.
Idempotency key tidak dikonsumsi — Kunci yang dikirim selama preflight tidak membuka baris di ledger, dan kunci (lock) yang sudah kedaluwarsa tidak dilepaskan. Jadi, kirimkan kunci yang memang akan Anda gunakan untuk panggilan sungguhan: preflight memberi tahu Anda apakah kunci itu masih bebas, akan memutar ulang (replay) eksekusi sebelumnya, atau berbenturan dengan perintah lain.
Dapat digabungkan dengan confirm — Kirim dry_run dan confirm bersamaan, dan pertanyaannya menjadi "jika saya mengonfirmasi, apa yang terjadi?". Tetap tidak ada yang dijalankan.
Preflight batch berlaku per batch — commands:batch juga menerima dry_run, tetapi penanda itu milik batch, bukan milik sebuah item (mengirimkannya pada item menghasilkan 422). Anda mendapat laporan per item ditambah total biaya kredit batch; saldo yang tidak mencukupi dilaporkan, bukan ditolak.
Tidak gratis — Setiap preflight menjalankan kueri sungguhan (pratinjau, saldo) dan dihitung terhadap rate limit. Jangan menjalankan preflight untuk seluruh katalog pada setiap deploy; jalankan preflight untuk perintah yang Anda ubah.
Idempotency: mengapa mencoba ulang tidak menghasilkan duplikat
ERP tidak membaca pesan error Anda, tidak melihat layar Anda, dan akan mengirim ulang permintaan yang sama setelah timeout. Bagian ini ada justru untuk perilaku tersebut.
Panggilan yang membawa idempotency_key dijalankan paling banyak satu kali. Panggilan kedua tidak mengeksekusi ulang perintah; panggilan itu mengembalikan hasil yang tercatat dengan status replayed. Ketika jaringan terputus, ketika permintaan mengalami timeout, atau ketika antrean mengambil job yang sama dua kali, Anda mendapatkan hasil pertama alih-alih faktur ganda.
Gunakan kunci pada setiap perintah tulis. Field read_only di katalog memberi Anda pembedaan itu secara cuma-cuma: setiap perintah dengan read_only: false layak mendapat idempotency key.
Strategi percobaan ulang Anda sebaiknya menggunakan exponential backoff dan membawa kunci yang SAMA pada setiap percobaan. Membuat kunci baru untuk setiap percobaan sama saja dengan tidak menggunakan idempotency sama sekali. Jangan mengirim kunci yang sama secara paralel: at-most-once (paling banyak satu kali) dijamin untuk percobaan ulang yang berurutan, bukan untuk dua permintaan yang saling berlomba.
Jebakan 1 — kegagalan juga ikut terkunci — Jika eksekusi pertama ditolak oleh aturan bisnis (failed), panggilan kedua dengan kunci yang sama mengembalikan error yang sama dan error_key yang sama, serta tidak mencoba ulang. Memperbaiki argumen lalu mencoba lagi memerlukan kunci BARU. Sebuah kunci mewakili satu percobaan, bukan satu niat.
Jebakan 2 — hasil yang besar diputar ulang tanpa body — Ledger hanya menyimpan hasil yang berukuran di bawah 64 KB. Hasil yang lebih besar diputar ulang dengan status replayed tetapi dengan body kosong. Integrasi Anda sebaiknya mengandalkan sinyal "replayed", bukan body-nya, lalu mengambil datanya dengan perintah get yang sesuai.
Jebakan 3 — sebuah kunci milik satu perintah — Mengirim kunci yang sama dengan perintah lain mengembalikan 409 idempotency_conflict beserta conflicting_command; tidak ada yang dijalankan dan tidak ada yang diputar ulang. Klien yang memakai satu kunci untuk dua verb adalah klien yang rusak, dan ia mengetahuinya dari sebuah error, bukan dari replay yang diam-diam.
Jebakan 4 — kunci berlaku 24 jam, bukan selamanya — Setelah 24 jam, kunci yang sama menjadi eksekusi baru. Percobaan ulang jaringan datang dalam hitungan menit; nomor dokumen ERP yang berulang setiap tahun tidak boleh tetap "replayed" selamanya. Katalog memublikasikan jendela waktu ini sebagai idempotency_ttl_hours.
Jebakan 5 — error server tidak mengunci kunci — 5xx server_error bukanlah penolakan bisnis: kuncinya tidak terikat, sehingga percobaan ulang dengan kunci yang sama benar-benar menjalankan perintahnya. Hanya failed yang mengunci (jebakan 1).
Cakupan dan format — perusahaan Anda, string apa pun, sebaiknya UUID — Keunikan ditegakkan pada (perusahaan Anda, kunci): INV-1001 milik tenant lain tidak pernah berbenturan dengan milik Anda dan tidak akan pernah dapat memutar ulang hasil Anda. Gunakan UUID biasa atau gabungan yang secara konstruksi unik, seperti {ERP-document-no}:{verb}.
Sinkronisasi inkremental dan paginasi
Jembatan ERP/CRM sebaiknya mengambil apa yang berubah, bukan mengambil semuanya setiap jam. Setiap perintah daftar — loads list, demands list-own, contacts list, invoices list, teammates list, load-groups list, reservations list, drivers list, tenders list, products search, warehouses search — menerima dua parameter bersama dan mengembalikan satu field bersama.
Mengapa tidak ada offset: pada tabel yang aktif, offset bergeser. Baris yang disisipkan di antara dua halaman membuat Anda melewatkan atau menghitung ganda sebuah rekaman, secara diam-diam. Cursor hanya bergerak maju, sehingga rekaman yang disisipkan atau diperbarui di tengah penelusuran akan muncul di akhir daftar: tidak ada yang hilang, tidak ada yang terduplikasi.
Muatan awal yang lengkap memakai mekanisme yang sama: mulai dengan updated_since=1970-01-01T00:00:00Z dan ikuti next_cursor hingga nilainya null. Tidak ada endpoint “ekspor” tersendiri karena memang tidak diperlukan.
Hal yang sama dengan lg: lg loads list --updated_since=2026-09-01T00:00:00Z --limit=100 --json, lalu lg loads list --cursor= --json.
Untuk sinkronisasi berikutnya, setel updated_since ke nilai updated_at terbesar yang Anda lihat. Timestamp memiliki presisi satu detik, sehingga rekaman yang tepat berada di batas dapat datang dua kali — tidak berbahaya selama Anda melakukan upsert berdasarkan external_ref atau kode di sisi Anda. Tanpa updated_since atau cursor, perintah berjalan dalam mode chat: urutan untuk manusia, paling banyak 20 baris, next_cursor bernilai null, dan truncated yang menyatakan “masih ada lagi”. Jangan gunakan mode itu untuk sinkronisasi.
Key error yang dapat dibaca mesin untuk bagian ini: INVALID_CURSOR, INVALID_UPDATED_SINCE, DUPLICATE_EXTERNAL_REF, EXTERNAL_REF_TOO_LONG, EXTERNAL_REF_INVALID. Semuanya menjawab HTTP 422 dengan error_code: "failed" dan result.error_key di body. Buat percabangan berdasarkan key-nya, jangan pernah berdasarkan teksnya.
updated_since — Timestamp ISO-8601 (disarankan UTC, misalnya 2026-09-01T00:00:00Z). Baris yang diperbarui pada atau setelah saat ini. Parameter ini mengalihkan perintah ke mode sinkronisasi: urutan tetap (updated_at, id) menaik, limit dibatasi hingga 100.
cursor — next_cursor dari respons sebelumnya, apa adanya. Cursor bersifat opaque dan bertanda tangan: jangan pernah membuat atau mengubahnya, jangan pernah memakai ulang cursor milik perusahaan lain atau milik perintah lain; semua itu ditolak dengan INVALID_CURSOR.
limit — Ukuran halaman. 1-100 dalam mode sinkronisasi (bawaan 10).
next_cursor (respons) — Cursor untuk halaman berikutnya. null berarti daftar sudah lengkap; inilah satu-satunya jawaban yang benar untuk “apakah masih ada lagi”.
total (respons) — Jumlah baris yang cocok dengan filter, tidak bergantung pada halaman — untuk pelaporan kemajuan.
Key milik Anda sendiri: external_ref
Jangan jadikan id auto-increment kami (invoice_id, contact_id) sebagai key bisnis di ERP Anda; id tersebut bersifat opaque dan privat untuk perusahaan Anda. Sebagai gantinya, muatan, permintaan angkutan, kontak, faktur, produk, dan gudang membawa key milik Anda.
Setel saat menulis — loads create, demands create, contacts create dan contacts update, invoices create menerima external_ref opsional (maks. 120 karakter) dan mengembalikannya tanpa perubahan.
Gunakan saat membaca — loads get --external_ref=ORD-2026-0917, invoices get --external_ref=..., contacts get --external_ref=..., demands get --external_ref=... semuanya berfungsi; pada perintah list dan search, --external_ref= adalah filter yang mencocokkan secara persis.
Unik per perusahaan — Rekaman kedua dengan key yang sama ditolak dengan 422 dan result.error_key = DUPLICATE_EXTERNAL_REF; key milik perusahaan lain menjawab “tidak ditemukan” kepada Anda. Pencocokan tidak membedakan huruf besar-kecil (ord-1 = ORD-1). Rekaman yang diarsipkan tetap memegang key-nya; pulihkan rekaman itu sebelum memakai ulang key tersebut.
Kirim juga idempotency_key — Percobaan ulang setelah timeout jaringan mengembalikan hasil pertama alih-alih membuat duplikat. Keduanya tidak dapat saling menggantikan: external_ref adalah key bisnis Anda, sedangkan idempotency_key mengidentifikasi satu percobaan.
Webhook keluar: kami mengirim POST kepada Anda ketika sesuatu terjadi
Semua yang dibahas sampai di sini adalah pull: Anda bertanya, kami menjawab. Jembatan ERP dulu harus bertanya sekali setiap menit untuk mengetahui bahwa sebuah muatan berganti status, sebuah faktur diterbitkan, atau sebuah penawaran masuk. Sekarang tidak lagi: daftarkan alamat https, pilih event yang Anda pedulikan, dan sebuah POST bertanda tangan akan tiba ketika event itu terjadi.
Push ditambahkan DI SAMPING pull, bukan sebagai penggantinya. Sinkronisasi inkremental (updated_since + cursor) tidak disentuh dan tetap merupakan alat yang tepat: muatan lengkap pertama, pengisian ulang riwayat (backfill), dan menjawab "apakah ada yang terlewat" semuanya berada di sana. Webhook memangkas latensi dari hitungan menit menjadi hitungan detik. Jembatan yang sehat menggunakan keduanya — webhook sebagai pemicu, sinkronisasi sebagai jaring pengaman.
Payload adalah SINYAL, bukan salinan rekaman. Payload membawa pengenal (id, external_ref milik Anda sendiri, status, waktu); Anda mengambil detailnya dengan kunci Anda sendiri melalui GET, dan panggilan itu sudah melewati gerbang otorisasi Anda sendiri. Dengan demikian, permukaan paparan tetap berada di tingkat pengenal. Dua field sengaja tidak disertakan: identitas perusahaan yang mengajukan penawaran (penawaran tertutup tampil dengan nama samaran di panel; menaruh identitasnya di webhook akan menembus privasi itu melalui kanal kedua) dan detail kontak reservasi (tidak perlu memindahkan data pribadi melalui kanal tambahan).
Nama event DIBEKUKAN. Jika makna sebuah nama berubah, nama baru dibuka dan nama lama tetap hidup selama jendela deprecation. Menambahkan field baru ke payload TIDAK menaikkan versi kontrak — konsumen wajib mengabaikan field yang tidak dikenalnya.
GET /api/common/integration-webhooks — Ledger beserta katalog event, batas, dan nama header. Setiap baris membawa alasan penonaktifannya dan ringkasan pengiriman 7 hari.
POST /api/common/integration-webhooks — 201 + { webhook, secret, shown_once: true }. Secret hanya muncul di sini.
PATCH /api/common/integration-webhooks/{uuid} — Nama / alamat / event / penanda aktif. TIDAK menyentuh secret.
DELETE /api/common/integration-webhooks/{uuid} — Menghapusnya: baris di-soft-delete (riwayat tetap dapat dikueri) dan pengiriman yang tertunda dibatalkan.
POST /api/common/integration-webhooks/{uuid}/rotate-secret — 201 + secret baru. Nilai lama berhenti berfungsi saat itu juga.
POST /api/common/integration-webhooks/{uuid}/test — Event ping — tanda tangan sungguhan, jalur sungguhan, jadwal percobaan ulang sungguhan.
GET /api/common/integration-webhooks/{uuid}/deliveries — Pengiriman terbaru: status, nomor percobaan, kode HTTP, durasi, tag error.
POST /api/common/integration-webhooks/deliveries/{uuid}/replay — Mengirim ulang satu pengiriman: event_id DIPERTAHANKAN, id pengiriman baru, payload disalin apa adanya.
Katalog event
Setiap event dari 13 event di bawah ini didukung oleh kelas event yang BENAR-BENAR di-dispatch. Tidak ada nama "sekadar bagus kalau ada" di katalog: event yang diumumkan tetapi tidak pernah dipicu adalah event yang ditunggu integrator selamanya, dan kegagalan itu terjadi tanpa suara. Tabel ini juga tidak ditulis tangan — tabel ini diambil dari katalog yang aktif setiap kali halaman dimuat.
invoice.payment_recorded sengaja TIDAK ADA: kelas event itu ada di kode tetapi tidak di-dispatch dari mana pun. Event pembayaran akan ditambahkan pada hari kelas itu benar-benar dipicu — tidak sebelumnya. Mengumumkan event lebih awal lebih buruk daripada tidak pernah menambahkannya.
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)
Memverifikasi tanda tangan
Setiap permintaan membawa header X-Logistivo-Signature: t=,v1=. String yang ditandatangani adalah "." dan algoritmanya HMAC-SHA256. Prefiks v1 menjaga agar skema ini dapat diberi versi: jika suatu saat datang skema kedua, header akan membawa t=…,v1=…,v2=… dan Anda memilih yang Anda kenal.
Kami memublikasikan dua penerima referensi tanpa dependensi, satu untuk Node dan satu untuk PHP murni. Keduanya menerapkan empat aturan di atas dan menguji dirinya sendiri dengan --selftest: tanda tangan valid, body yang diubah, secret yang salah, timestamp di luar jendela, header yang rusak, jebakan serialisasi ulang, dan kedua jenis pengulangan (pengiriman yang sama / fakta yang sama). Verifier-nya adalah padanan persis dari kode yang kami gunakan sendiri — kami memakai kontrak yang kami publikasikan.
Verifikasi body MENTAH — Tanda tangan dihitung atas byte. Men-decode lalu menserialisasi ulang body (JSON.stringify(req.body), json_encode($request->all())) mengubah DATA yang sama menjadi BYTE yang berbeda, dan tanda tangannya tidak lagi cocok. Di Node, jebakannya adalah format angka (1.50 di jalur kiriman menjadi 1.5; bilangan bulat besar kehilangan presisi), di PHP jebakannya adalah escaping karakter (/ menjadi \/, İ menjadi İ). Gunakan express.raw di Express dan $request->getContent() di Laravel. Inilah kesalahan paling umum saat menulis penerima (receiver).
Periksa timestamp — t berada DI DALAM tanda tangan. Jika hanya tanda tangan yang diverifikasi, siapa pun yang menangkap permintaan yang valid dapat memutarnya ulang beberapa jam kemudian, dan penerima akan menganggapnya sebagai event yang terverifikasi. Buang setiap permintaan dengan |now − t| > tolerance meskipun tanda tangannya benar. Jendela yang disarankan adalah 300 detik.
Bandingkan dalam waktu konstan — hash_equals / timingSafeEqual. Membandingkan dengan == memungkinkan penyerang menebak tanda tangan byte demi byte.
Deduplikasi berdasarkan event_id, bukan id — event_id mengidentifikasi FAKTA: nilainya sama untuk dua pelanggan langganan yang menerima event yang sama, dan nilainya DIPERTAHANKAN saat replay. id (= X-Logistivo-Delivery) mengidentifikasi PENGIRIMAN dan berubah saat replay. Jawab "apakah saya sudah menangani ini" dengan event_id; menjawabnya dengan id membuat replay menjalankan pekerjaan yang sama dua kali.
Pengiriman, percobaan ulang, dan penonaktifan
Penerima Anda tidak akan selalu aktif. Jalur ini mengasumsikan hal itu: kegagalan sementara masuk ke jadwal percobaan ulang, kegagalan permanen menonaktifkan langganan — dan ALASAN penonaktifan selalu dicatat.
Alasan penonaktifan dapat dibaca mesin dan stabil (delivery_failures, endpoint_gone, unsafe_target, key_revoked, by_user), serta muncul baik di panel maupun di `lg webhooks list`. Penonaktifan tanpa alasan akan membuat pertanyaan "mengapa tidak ada yang masuk" tidak dapat dijawab. Mengaktifkan kembali akan mereset penghitung dan stempelnya.
Anda yang menulis alamatnya; server KAMI yang membuat permintaannya. Tanpa gerbang, tenant yang memasukkan alamat metadata cloud dapat membuat kami mengirim permintaan dari dalam jaringan kami sendiri. Karena itu, alamat diperiksa baik saat didaftarkan maupun pada SETIAP pengiriman:
Timeout — Total 8 detik, 4 detik untuk terhubung — penerima yang lambat tidak boleh menyita worker. Masukkan pekerjaan ke antrean dan segera kembalikan 2xx.
Jadwal percobaan ulang — 60 · 300 · 1800 · 7200 · 21600 detik → 6 percobaan, jendela waktu sekitar 8,6 jam.
Satu-satunya kegagalan permanen: 410 Gone — Artinya "hapus saya": tidak ada percobaan ulang, langganan langsung dinonaktifkan. JANGAN PERNAH mengembalikan 410 untuk kegagalan tanda tangan.
Setiap kegagalan lainnya — SEMUANYA dicoba ulang, termasuk 4xx. Kehilangan event bisnis lebih mahal daripada beberapa permintaan tambahan: penerima yang mengembalikan 403 saat aturan WAF sedang diperbarui akan diam-diam kehilangan event "faktur diterbitkan" pada jalur yang menganggap 4xx sebagai permanen.
Retry-After — Dipatuhi pada 429 dan 503 (dibatasi maksimal 6 jam).
Redirect — TIDAK diikuti. Melompat ke alamat internal melalui 302 akan menembus gerbang alamat lewat rute kedua.
Penonaktifan otomatis — Setelah 10 pengiriman berturut-turut yang kehabisan percobaan. 410, target yang tidak aman, dan pencabutan kunci integrasi yang terhubung menonaktifkan SEKETIKA.
hanya https, hanya port 443/8443, kredensial yang disematkan (https://user:pass@…) ditolak;
localhost, nama berlabel tunggal, dan sufiks internal seperti .internal / .local / .svc ditolak — niatnya ditolak bahkan sebelum hasil resolusi diperiksa, sehingga split-horizon DNS tidak dapat menembus gerbang;
literal IP dan SEMUA rekaman hasil resolusi DNS harus publik. Jika sebuah nama di-resolve ke alamat publik sekaligus alamat privat, tidak ada yang menanyakan kepada kami mana yang harus dipilih → nama itu langsung ditolak;
pada saat pengiriman, alamat di-resolve satu kali dan koneksi dipatok ke alamat yang sudah diverifikasi: jendela DNS rebinding tertutup;
BODY respons penerima tidak pernah disimpan di mana pun (hanya kode status, durasi, dan tag error singkat) — sehingga jalur "baca", yang merupakan nilai sebenarnya dari sebuah celah di gerbang alamat, tetap tertutup.
Sengaja TIDAK ada sakelar konfigurasi untuk "mengizinkan alamat privat": sakelar seperti itu suatu hari akan tertinggal dalam keadaan menyala secara tidak sengaja.
Dikembalikan SATU KALI, hanya saat langganan dibuat dan saat rotate-secret. Secret disimpan dalam bentuk terenkripsi di server dan tidak akan pernah dapat dibaca kembali; tidak ada "tampilkan lagi".
lg mencetaknya ke layar dan membiarkannya di sana — lg tidak menuliskannya ke file konfigurasi atau file cache mana pun.
Jika hilang, Anda melakukan rotasi; nilai lama berhenti berfungsi SAAT ITU JUGA. Untuk peralihan yang mulus, penerima Anda sebaiknya mencoba kedua secret selama masa transisi.
Mengubah alamat TIDAK menyentuh secret: pemeliharaan rutin seperti "URL-nya pindah" tidak boleh merusak verifikasi di sisi penerima.
Kesehatan dan status: tidak boleh ada yang menyadari jembatan yang senyap sebelum Anda
Jembatan integrasi jarang mati dengan suara keras. Biasanya ia menjadi senyap pada dini hari: sebuah token kedaluwarsa, orang yang diwakili oleh kunci keluar dari tim, sebuah scope dipersempit, atau endpoint penerima mulai mengembalikan 403. Pihak pertama yang menyadarinya hampir selalu adalah pelanggan. lg status hadir untuk membalik urutan itu.
Satu perintah menjawab dua pertanyaan sekaligus, karena saat terjadi gangguan keduanya ditanyakan pada saat yang sama: apakah platform berjalan, dan apakah jembatan saya sehat. Baris platform berfungsi tanpa token — saat terjadi kegagalan, token itu sendiri adalah tersangka pertama, dan mengikat pertanyaan status pada token akan membuat Anda tidak mendapat jawaban tepat ketika Anda membutuhkannya.
Ringkasan kesehatan tidak menyimpan ledger baru; ringkasan ini merangkum tiga sumber yang sudah ada menjadi satu kalimat: penghitung penggunaan harian (berapa banyak Anda memanggil dan berapa banyak yang gagal), ledger permintaan (permintaan mana, kapan, dan mengapa ditolak), dan ledger pengiriman webhook keluar (apakah event sampai ke penerima). Tingkat error selalu dibaca dari penghitung harian; ledger detail memiliki batas dan menyatakannya dengan jelas ketika batas itu tercapai.
Ringkasan yang sama muncul di panel: di bawah Settings › Integration › Keys, setiap baris membawa sebuah badge dan, di bawahnya, alasannya. Ambang batas tidak dihitung di sisi klien; tingkat apa pun yang ditetapkan server, itulah yang ditampilkan baik oleh panel maupun oleh lg status, sehingga kedua layar tidak akan pernah menyatakan hal yang berbeda tentang kunci yang sama.
Watchdog Anda tidak memerlukan token. Endpoint ini hanya mengembalikan kata-kata status; endpoint ini tidak membawa versi, nama host, nama antrean, jumlah job, teks error, atau data pelanggan — dan memang tidak bisa.
Ringkasan kesehatan dihasilkan dengan jumlah kueri yang konstan per permintaan; jumlah kueri tidak bertambah seiring jumlah kunci. Untuk detail, baca permintaan terbaru dari kunci tersebut dengan lg logs dan jembatan keluar dengan lg webhooks list.
SEHAT — Tidak ada gangguan yang terukur dan kami memegang bukti keberhasilan: panggilan yang berhasil di ledger, atau lalu lintas yang tetap bebas error di penghitung.
PERHATIAN — Sesuatu mulai rusak: tingkat error atau rentetan kegagalan berturut-turut melewati ambang batas, permintaan ditolak di gerbang, kunci hampir kedaluwarsa, atau jembatan yang biasanya rutin berkomunikasi menjadi senyap.
GAGAL — Jembatan tidak berfungsi saat ini: token dicabut tanpa disengaja, kunci yang sudah ditutup masih dipanggil, terjadi lima kegagalan berturut-turut, tingkat error di atas lima puluh persen, atau langganan webhook dinonaktifkan.
DITUTUP — Kunci sengaja ditutup dan tidak ada yang memanggilnya. Itu adalah keputusan, bukan gangguan — dan tidak ditampilkan dengan warna merah.
TIDAK ADA DATA — Tidak ada pengukuran: kunci tidak pernah dipanggil, atau pengukurannya sendiri gagal. Tidak satu pun dari keduanya berwarna hijau.
Tidak ada hijau palsu. Badge sehat memerlukan bukti keberhasilan yang terukur; kunci yang tidak pernah dipanggil tidak akan pernah menjadi hijau, karena tidak ada satu pun pengukuran yang menunjukkan bahwa kunci itu berfungsi.
Tidak ada merah palsu. Kunci yang sengaja Anda tutup ditampilkan sebagai Ditutup. Mewarnai semuanya merah membuat warna merah kehilangan makna; kunci yang ditutup baru menjadi merah jika masih dipanggil setelah ditutup — dan pada saat itu sebuah jembatan memang benar-benar rusak.
Tidak dapat mengukur tidak sama dengan tidak ada data. Jika sebuah kueri gagal di sisi server, baris tersebut tidak diam-diam menampilkan nol; baris itu menyatakan bahwa pengukuran tidak dapat dilakukan.
Kesenyapan selalu dilaporkan, tetapi tidak pernah serta-merta diubah menjadi peringatan. Jembatan akhir bulan yang senyap selama tiga puluh jam adalah hal normal; jembatan yang berkomunikasi pada sedikitnya lima dari tujuh hari terakhir lalu menjadi senyap adalah gangguan. Ritmenya diukur, bukan diasumsikan.
Kueri status itu sendiri tidak mencemari angka kesehatan. Panggilan yang dibuat oleh lg status muncul di ledger permintaan tetapi dikecualikan dari perhitungan kesehatan — jika tidak, kueri status Anda sendiri yang berhasil akan mereset rentetan kegagalan dan menyembunyikan gangguan yang justru ingin ditampilkan oleh layar itu.
Setiap baris diukur: kueri sungguhan dijalankan terhadap database, katalog perintah benar-benar dibangun, rekaman aktif dari queue worker benar-benar dibaca. Tidak ada yang diasumsikan.
Respons itu sendiri juga merupakan pengukuran: jika Anda dapat membaca body-nya, tier web sedang berjalan.
Tingkat teratas hanya diturunkan dari komponen yang wajib. Ketika antrean berhenti, jawabannya adalah degraded, bukan down — panggilan API sinkron tidak memerlukan antrean, dan menyatakan platform down akan menjadi alarm palsu.
Ketika keadaan antrean tidak dapat diukur, tingkat teratas dibiarkan utuh: tidak tahu tidak sama dengan mengukur bahwa sesuatu rusak.
Jika platform down, endpoint mengembalikan HTTP 503. Body-nya tidak memakai envelope agar tool pemantauan dapat memberi peringatan tanpa mem-parsing-nya, dan responsnya tidak pernah disimpan di cache mana pun.
Error dan kode keluar
Yang menjadi dasar percabangan bagi mesin adalah string yang stabil. Teks di field error ditujukan untuk manusia, dilokalkan, dan berubah tanpa pemberitahuan — integrasi yang membuat percabangan berdasarkan teks pesan tidak didukung, dan jika integrasi itu rusak, hal itu bukan bug.
Dua taksonomi, dua field. error_code adalah lapisan transport (tabel di atas) dan merupakan dasar percabangan pertama Anda. error_key adalah key aturan bisnis yang stabil di dalam failed — INSUFFICIENT_CREDITS, NOT_FOUND, DUPLICATE_CONTACT, INSUFFICIENT_STOCK — yang dipublikasikan sebagai kamus di katalog (error_keys) dan di bawah ini. Perintah yang belum mengeluarkan key mengembalikan error_key: null; perlakukan key yang tidak ada di kamus sebagai kegagalan umum.
ok — HTTP 200 · error_code — · CLI 0 · —
replayed — HTTP 200 · error_code — · CLI 0 · Replay idempoten; pekerjaan TIDAK dijalankan lagi.
failed — HTTP 422 · error_code failed · CLI 1 · Tidak — ditolak oleh aturan bisnis (lihat error_key). Tidak ada gunanya sampai argumennya berubah.
needs_confirmation — HTTP 409 · error_code needs_confirmation · CLI 4 · Ya, dengan confirm: true.
idempotency_conflict — HTTP 409 · error_code idempotency_conflict · CLI 2 · Tidak — kunci itu pertama kali digunakan untuk perintah lain (conflicting_command). Buat kunci baru.
forbidden — HTTP 403 · error_code forbidden · CLI 3 · Tidak — gerbang peran, atau kunci dengan scope baca pada perintah tulis.
not_found — HTTP 404 · error_code not_found · CLI 2 · Tidak — nama perintah salah atau sudah dihapus.
(schema) — HTTP 422 · error_code invalid_request · CLI 2 · Tidak — body permintaan atau sebuah argumen gagal dalam validasi schema (errors{}); ini bukan aturan bisnis.
server_error — HTTP 500 · error_code server_error · CLI 6 · Ya — exponential backoff dengan idempotency key yang SAMA; kunci itu tidak dikunci.
401 unauthenticated — Token sudah kedaluwarsa atau dicabut. Mencoba ulang tidak akan membantu; token harus diganti.
429 rate_limited — Terkena rate limit untuk token ini. Respons selalu membawa Retry-After dan body dengan retry_after, limit, dan bucket; patuhi itu alih-alih membuat jeda tetap sendiri. lg menunggu dan mencoba ulang hingga tiga kali, lalu keluar dengan kode 5.
5xx server_error / network error — Coba ulang dengan exponential backoff dan idempotency key yang SAMA. Mengganti kunci akan menjalankan ulang pekerjaan yang mungkin sudah diselesaikan server. lg mencoba ulang tiga kali (1 s, 2 s, 4 s), lalu keluar dengan kode 6 dengan error_code network_error atau server_error.
Janji stabilitas
Pertanyaan paling mahal dalam kontrak integrasi adalah “apakah kode yang saya tulis hari ini masih berjalan besok?” Satu angka menjawabnya: contract_version di katalog, dan header X-Contract-Version pada setiap respons. Angka itu menjawab tepat satu pertanyaan — apakah kode yang ditulis sebelumnya masih berjalan tanpa perubahan? Jika angkanya tidak naik, ya. Jika naik, tidak: sesuatu yang Anda andalkan telah dihapus atau dipersempit.
Karena pengumuman tidak menghapus apa pun: kode Anda yang sudah ada berjalan persis seperti sebelumnya, pada hari setelahnya. Menaikkan versi saat pengumuman akan memancarkan dua sinyal untuk satu perubahan dan melatih Anda untuk mengabaikan sinyal pertama — melemahkan sinyal yang benar-benar penting. Pengumuman itu sudah ikut dalam panggilan yang Anda lakukan: deprecated_at dan replaced_by pada baris katalog, header X-Deprecated ditambah blok deprecated pada respons perintah tersebut, dan peringatan satu baris di stderr jika Anda menggunakan lg. Anda tidak perlu melakukan apa pun untuk mengetahui bahwa sesuatu akan dihapus; informasinya sudah ada di log Anda.
Paling sedikit dua kuartal kalender berlalu antara pengumuman dan penghapusan. Sepanjang jendela tersebut, perintah lama tetap menjawab dan memberi peringatan pada setiap panggilan. Ketika sebuah nama CLI dipensiunkan, penggantinya mengambil alih nama itu sebagai alias: selama jendela, nama lama mencapai perintah lama, dan pada hari perintah lama dihapus, panggilan yang sama mendarat di perintah baru — tanpa Anda perlu merilis versi klien.
preview_invoice → get_invoice (diumumkan 3 September 2026). get_invoice mengembalikan blok pratinjau yang sama dan menambahkan baris item, rincian pajak, pembayaran yang tercatat, sisa saldo, serta pengalamatan dengan key ERP milik Anda sendiri (external_ref). preview_invoice tetap berfungsi, demikian pula lg invoices preview — keduanya memberi peringatan.
tidak berubah — Perintah baru · parameter OPSIONAL baru · field respons baru · key error baru · endpoint baru — Tidak perlu melakukan apa pun. Anda wajib mengabaikan field yang tidak Anda kenal; parser yang gagal karena field yang tidak dikenal tidak memenuhi kontrak.
tidak berubah — PENGUMUMAN deprecation: pemberitahuan bahwa sebuah perintah akan dihapus — Kode Anda tetap berjalan. Masukkan tugas ke kalender Anda — jendelanya paling sedikit 6 bulan.
naik — Menghapus perintah · memensiunkan nama CLI lama · menghilangkan field respons · menjadikan parameter opsional sebagai wajib · mempersempit enum — Artinya Anda melewatkan jendelanya; pemberitahuannya sudah sampai kepada Anda di tiga tempat yang berbeda.
Nama API sebuah perintah (seperti list_loads) dibekukan untuk selamanya; itulah nama yang Anda gunakan dalam panggilan HTTP.
error_code (transport) dan error_key (aturan bisnis) adalah string yang stabil. Key baru dapat muncul — perlakukan key yang tidak dapat Anda temukan di kamus sebagai kegagalan umum, bukan sebagai kerusakan.
Pemetaan antara status HTTP dan field status di body bersifat tetap.
Nomor versi tidak pernah turun, dan dapat dibaca pada setiap respons — termasuk 304 dan 429 yang tanpa body.
TEKS error dan deskripsi. Teks ini dilokalkan dan berubah tanpa pemberitahuan; percabangan berdasarkan teks pesan tidak didukung.
Ketiadaan field yang tidak Anda kenal. Menambahkan field tidak menaikkan versi.
Id auto-increment sebagai key bisnis. Bawa key milik Anda sendiri dengan external_ref.
Key error dinamis yang diturunkan dari nama kelas; key tersebut bukan bagian dari kontrak.
Tabel identitas perintah
Tabel di bawah ini tidak ditulis tangan: tabel ini dibuat dari registri perintah yang aktif setiap kali halaman ini disajikan. Perintah yang ditambahkan di server muncul di sini dengan sendirinya. Kolom "Gerbang" memberi tahu Anda apakah sebuah perintah meminta konfirmasi dan apakah efeknya dapat dibatalkan; kolom "Peran" memberi tahu Anda jenis akun mana yang akan menemukan perintah itu di katalognya. Badge menandai perintah yang memerlukan kunci tingkat manager, perintah yang menerima file, dan perintah yang hanya berjalan dari lg.
Perintah dikelompokkan menurut fungsi, masing-masing di halamannya sendiri. Pilih fungsi untuk membuka tabel perintahnya.
Nama API (list_loads) dibekukan dan tidak akan berubah; itulah nama yang Anda gunakan dalam panggilan HTTP. Identitas CLI (loads list) diatur oleh kebijakan versioning: begitu diumumkan, identitas itu hanya berubah dengan kenaikan versi dan jendela migrasi, yang selama itu katalog melayani pasangan lama sebagai alias. Deskripsi di sini berasal dari rekaman milik setiap perintah dan dipersingkat — untuk teks lengkap, tipe parameter, dan nilai enum, baca endpoint katalog atau jalankan lg help . Perintah khusus afiliasi tidak tercantum di sini; akun afiliasi melihatnya di katalognya sendiri.
Muatan dan pelacakan — Membuat muatan, pihak terkait, dokumen, tautan pelacakan, tanda tangan serah terima, ETA, dan pengecualian. 115 perintah — /id/developers/cli/loads
Perbatasan dan kepabeanan — Pemeriksaan kesiapan perbatasan, antrean di perbatasan dan pelabuhan, dokumen ekspor, pelaporan U-ETDS. 42 perintah — /id/developers/cli/border
Permintaan dan penawaran — Membuka permintaan angkutan, meminta dan mengajukan penawaran, tender, pengangkut di jaringan Anda. 42 perintah — /id/developers/cli/quotes
Kartu tarif dan penawaran penjualan — Kartu tarif yang disepakati, kaskade penawaran, dan penawaran penjualan kepada pelanggan. 57 perintah — /id/developers/cli/pricing
Armada dan pengemudi — Pengemudi, kendaraan, struk pengeluaran, rekening pengemudi, perencanaan perjalanan, dan hari Schengen. 115 perintah — /id/developers/cli/fleet
Gudang dan stok — Gudang, reservasi, janji dok, layar gerbang, produk, stok, dan palet. 69 perintah — /id/developers/cli/warehouse
Akuntansi dan faktur — Faktur, audit faktur pembelian, Paraşüt, jurnal, penerimaan dan pembayaran, margin. 95 perintah — /id/developers/cli/finance
Pesan dan email — Obrolan muatan, pesan langsung, draf dan kotak masuk email, notifikasi. 58 perintah — /id/developers/cli/messages
Tarif dan tindakan perdagangan — Pencarian kode HS, bea masuk, tindakan antidumping, laporan karbon. 20 perintah — /id/developers/cli/tariffs
Perusahaan dan tim — Direktori perusahaan, relasi dan dokumen, anak perusahaan, rekan tim dan undangan. 65 perintah — /id/developers/cli/contacts
Otomasi dan laporan — Aturan otomasi, laporan khusus, berkas Excel dan PDF, rencana kerja. 27 perintah — /id/developers/cli/automation
Akun dan integrasi — Pengaturan akun dan bahasa, kunci integrasi, paket, kredit, dan dompet. 16 perintah — /id/developers/cli/account
Integrasi ERP dan CRM — Identitas: tidak ada akun layanan, melainkan pengguna yang nyata
ERP atau CRM terhubung ke Logistivo sebagai pengguna perusahaan yang nyata, yang memegang personal access token yang dibuat dari panel. Akun layanan sintetis — tanpa perusahaan, dikecualikan dari pembatasan cakupan, tanpa ada yang bertanggung jawab atasnya — tidak pernah dibuat.
Ini adalah arsitektur, bukan preferensi. Isolasi multi-tenant sepenuhnya bertumpu pada perusahaan milik pengguna; untuk identitas tanpa perusahaan, cakupan isolasi menjadi tidak berfungsi, dan satu kueri yang salah dengan token itu akan membaca data yang bukan miliknya. Alasan kedua adalah audit: kolom pengguna di log mengaitkan "siapa yang menjalankan ini" dengan seseorang; akun layanan membuat kolom itu tidak bermakna dan meninggalkan integrasi yang menerbitkan faktur tanpa pemilik. Alasan ketiga adalah pencabutan: jika token milik seseorang, integrasi akan berhenti ketika orang itu keluar. Jembatan tanpa pemilik adalah jembatan yang terus menulis diam-diam selama bertahun-tahun.
Dalam praktiknya: perusahaan membuat pengguna biasa di panel (misalnya "ERP Bridge", yang dimiliki oleh seorang karyawan yang disebut namanya), memberinya peran yang sempit, membuat token dari sesi pengguna tersebut, lalu menaruhnya di ERP.
Pengguna itu terlihat di sistem izin, haknya dapat dipangkas, dan tokennya dapat dicabut secara tersendiri. Yang dilarang bukanlah membuat akun — melainkan membuat akun yang tidak terikat pada sebuah tenant.
Satu integrasi per token. Jika dua sistem berbagi satu token, granularitas pencabutan hilang: memutus CRM berarti memutus ERP juga.
Integrasi ERP dan CRM — Versioning dan deprecation
Respons katalog membawa bilangan bulat contract_version; baris perintah membawa since, deprecated_at, dan replaced_by. Versi kontrak hanya naik pada perubahan yang merusak kompatibilitas (breaking change).
Versi TIDAK naik untuk: perintah baru, parameter opsional baru, field baru dalam respons. Konsumen wajib mengabaikan field yang tidak dikenalnya; klien yang menghasilkan error karena field yang tidak dikenal tidak memenuhi kontrak.
Versi NAIK untuk: menghapus atau mengganti nama perintah, menghapus field respons, menjadikan parameter opsional sebagai wajib, mempersempit enum. Bentuk lama tetap hidup paling sedikit dua kuartal kalender (6 bulan) dengan deprecated_at dan replaced_by.
Deprecation diumumkan di katalog, tidak hanya di changelog. Karena klien membangun dirinya dari katalog, perintah dengan deprecated_at yang terisi akan mencetak peringatan tanpa rilis klien apa pun, dan integrator melihatnya di log mereka.
Nama API dibekukan untuk selamanya. Identitas CLI (domain/verb) boleh diubah dengan bebas sebelum diumumkan; setelah diumumkan, identitas itu hanya berubah dengan kenaikan versi dan jendela migrasi, yang selama itu pasangan lama dilayani sebagai alias.
Dalam praktiknya: respons katalog dan header X-Contract-Version membawa versi; setiap baris perintah membawa since, deprecated_at, replaced_by, dan aliases (pasangan domain/verb lama). Memanggil perintah yang sudah usang tetap berfungsi dan menjawab dengan header X-Deprecated: name; deprecated_at=…; replaced_by=… ditambah objek deprecated di body. ?domain= pada katalog me-resolve domain alias lama ke perintah yang berlaku saat ini.
Klien yang memahami versi 1 lalu menemui angka yang lebih besar sebaiknya mencatat peringatan dan terus berjalan; lg melakukan persis hal itu. Pemensiunan yang berlaku tercantum dalam janji stabilitas di atas.
Integrasi ERP dan CRM — Pengenal yang stabil: jangan pernah menyerahkan id auto-increment ke ERP Anda sebagai key
Id auto-increment internal bersifat opaque dan dibatasi per tenant: id valid milik perusahaan lain mengembalikan "tidak ditemukan" kepada Anda, bukan data. Namun sifat opaque tidak menjadikannya key bisnis. Yang disimpan ERP dalam rekamannya sendiri haruslah key bisnis.
Muatan: code (kode pelanggan, misalnya FSK2158). loads get sudah berfungsi berdasarkan kode.
Negara: ISO 3166-1 alpha-2. countries search mengembalikan kodenya.
HS / tarif: kode itu sendiri — nomenklaturnya sudah universal.
Faktur: nomor faktur, setelah diterbitkan. Draf hanya memiliki surface id, dan id draf BUKAN key bisnis — ERP sebaiknya membawa referensinya sendiri dan tidak pernah menyimpan id draf secara permanen.
Produk, gudang, kontak: saat ini hanya surface id. Aturan untuk perintah baru bersifat eksplisit: setiap perintah yang mengembalikan surface id juga mengembalikan key bisnis milik tenant itu sendiri (SKU, kode, nomor pajak) agar ERP dapat mencocokkannya di sisinya.
Integrasi ERP dan CRM — Paginasi, filter, dan sinkronisasi inkremental
Perintah daftar menerima limit dan mengembalikan count. Untuk sinkronisasi malam hari, kontrak berkomitmen pada hal-hal berikut; perintah daftar yang sudah menerapkannya mencantumkan cursor dan updated_since di JSON Schema-nya, dan sampai hal itu terjadi, perlakukan perintah tersebut sebagai jendela kecil (batas atas 20 baris, tanpa cursor).
Permintaan: limit (1..batas atas per perintah) ditambah cursor (opaque, hanya bergerak maju, ditandatangani oleh server). offset TIDAK digunakan — pada tabel yang aktif, offset bergeser; rekaman yang disisipkan di antara dua halaman membuat ERP melewatkan sebuah baris atau menghitungnya dua kali, dan hal itu terjadi secara diam-diam.
Respons: { count, total?, next_cursor|null }. count adalah jumlah baris dalam respons ini; ketika next_cursor bernilai null, daftar sudah lengkap. Kirimkan kembali next_cursor tanpa perubahan — nilainya bukan nomor halaman dan bukan sesuatu yang boleh Anda bangun sendiri.
Cursor yang diubah atau milik pihak lain ditolak dengan 422 invalid_request; sebuah cursor terikat pada perusahaan yang menerimanya dan tidak dapat digunakan untuk menelusuri data tenant lain.
Filter: parameter bernama di JSON Schema, digabungkan dengan AND. Tidak ada bahasa kueri bebas — sebuah DSL akan menjadi permukaan kueri kedua yang harus kami pertahankan.
Sinkronisasi inkremental: updated_since (ISO-8601, UTC) ditambah cursor. Simpan updated_at terbaru yang pernah Anda lihat dan kirimkan kembali pada eksekusi berikutnya; tanpa itu, setiap ERP mengambil ulang semuanya setiap jam.
Referensi eksternal: perintah tulis menerima external_ref (key dokumen milik Anda sendiri), unik per perusahaan; create kedua dengan external_ref yang sama ditolak alih-alih diduplikasi, dan list/get mengembalikannya agar Anda dapat mencocokkan rekaman di sisi Anda.
Integrasi ERP dan CRM — Rate limit
Key pembatasnya adalah token, bukan IP: ERP datang dari balik satu NAT, dan pembatasan berbasis IP akan menghitung seluruh perusahaan sebagai satu pengguna. Dua integrasi dengan dua kunci tidak pernah saling menghabiskan kuota — inilah alasan kedua untuk "satu integrasi per kunci".
Penemuan tanpa autentikasi (public/cli/catalog): 30 per menit. Ini adalah kamus, bukan sumber data; bacalah sekali saat menulis jembatan Anda, jangan pernah dalam loop produksi.
Endpoint katalog (GET common/commands, GET common/commands/{name}): 120 per menit per token. Katalog jarang berubah dan menjawab 304 untuk If-None-Match; jangan mengambilnya ulang sebelum setiap perintah — lg menyimpannya di cache selama satu jam.
Perintah baca (POST common/commands/{name} dengan read_only: true): 120 per menit per token.
Perintah tulis (POST common/commands/{name} dengan read_only: false; nama yang tidak dikenal juga dihitung di sini): 30 per menit per token. Penulisan memiliki efek samping; loop yang lepas kendali akan ditagih.
Perintah yang memakai kredit (credit_cost pada baris katalog tidak nol — misalnya tariffs inquiry dan export-documents generate): batas yang sebenarnya adalah KREDIT, bukan jumlah permintaan. Respons 200 mungkin sudah memakai kredit.
Batas atas harian per perusahaan, dibagi bersama panel: perintah yang mengirim e-mail atau push kepada orang di luar perusahaan Anda menggunakan jatah 300 notifikasi keluar per hari, dan memulai pelacakan kontainer atau kapal berbayar menggunakan jatah 100 per hari. Jika melewati batas atas, perintah menjawab DAILY_LIMIT_REACHED dengan retry_after; unggahan file memiliki batas atasnya sendiri (lihat Perintah yang menerima file).
429 selalu membawa Retry-After dan body { error_code: "rate_limited", retry_after, limit, bucket }; patuhi itu alih-alih membuat jeda tetap sendiri. Katalog memublikasikan angka-angka terkini di bawah rate_limits.
Integrasi ERP dan CRM — Hal-hal yang tidak akan kami lakukan
Ini sering kali merupakan bagian paling berguna dari sebuah kontrak: mengetahui apa yang tidak akan pernah datang memungkinkan Anda merancang dengan memperhitungkannya.
Tidak ada akun layanan dan tidak ada principal yang tidak terikat pada sebuah tenant.
Tidak ada pembayaran, nomor kartu, atau persetujuan hukum melalui API atau chat. Langkah-langkah itu tetap berada di browser milik orang yang bersangkutan; sebuah perintah memberikan tautannya kepada Anda.
Tidak ada jalur kedua: tidak ada akses langsung ke database, tidak ada akses shell, dan tidak ada endpoint massal yang melewati satu titik penegakan tersebut. Gerbang peran, gerbang konfirmasi, idempotency, dan log audit hanya ditegakkan di sana.
Percabangan berdasarkan teks pesan error tidak didukung; teksnya dilokalkan dan berubah tanpa pemberitahuan.
Tidak ada paginasi offset.
Menggunakan surface id sebagai key bisnis di ERP Anda tidak didukung.
Webhook keluar tidak dijejalkan ke dalam kontrak ini — tetapi kini webhook SUDAH ADA dan didokumentasikan di halaman ini (bagian webhook di atas). Katalog adalah permukaan PULL dan aliran event adalah kontrak yang TERPISAH: nama event dan schema payload diberi versi menurut aturannya sendiri dan tidak terikat pada versi kontrak katalog perintah.
Katalog yang dapat dibaca mesin
Halaman ini ditulis untuk manusia. Untuk asisten AI atau klien otomatis, informasi yang sama tersedia sebagai salinan terstruktur tanpa autentikasi.
GET /api/public/cli/catalog tidak memerlukan autentikasi dan mengembalikan identitas publik perintah-perintah: nama API yang dibekukan, identitas domain/verb CLI, deskripsi, parameter JSON Schema, penanda read_only, confirmation_needed, dan irreversible, credit_cost, serta field akses key_level, permission, file_params, secret_parameters, dan cli_only. Endpoint ini tidak mengembalikan data pribadi, data tenant, ataupun contoh rekaman — hanya gambaran permukaannya.
Cara yang benar bagi agen eksternal untuk menggunakannya: baca katalog, jelaskan dengan kata-kata ANDA SENDIRI pekerjaan apa saja yang mungkin dilakukan, dan ketika eksekusi diperlukan, arahkan pengguna untuk menjalankannya di lingkungan mereka sendiri dengan token mereka sendiri. Agen tidak pernah meminta, membuat, atau meneruskan token milik pengguna.
Menghubungkan Logistivo ke asisten AI untuk pendaftaran dan permintaan angkutan adalah kanal terpisah dengan halamannya sendiri:
Katalog tidak memerlukan autentikasi; eksekusi memerlukannya. Tidak ada cara untuk menjalankan perintah atas nama sebuah agen — yang berjalan selalu adalah identitas pengguna itu sendiri.
Kata sandi Logistivo, kode verifikasi, atau access token tidak pernah melewati chat. Jangan membangun alur yang meminta, membuat, atau meneruskannya.
Apakah sebuah perintah tidak dapat dibatalkan tertulis di katalog. Jangan pernah menyarankan "mari kita coba" pada perintah dengan irreversible: true.
Perintah yang credit_cost-nya tidak nol (misalnya tariffs inquiry dan export-documents generate) memiliki konsekuensi biaya; jangan memanggilnya dalam loop otomatis.
Pembayaran, nomor kartu, dan persetujuan hukum tidak pernah melewati chat atau agen. Sebagai gantinya, tawarkan tautan dari handoff-links generate; orang itu menyelesaikan langkahnya di browser miliknya sendiri.
Agen yang bertindak dengan kunci milik pengguna sebaiknya memanggil users get terlebih dahulu: perintah itu mengembalikan peran, tingkat akses kunci, izin yang efektif, dan apakah ada persetujuan atau verifikasi telepon yang tertunda yang memblokir penulisan — prediksi penolakan alih-alih mengumpulkannya.
Kembaran halaman ini dalam teks biasa tersedia di /cli.md; gunakan itu jika Anda mem-parsing markdown lebih andal daripada HTML.
Definisi yang dapat dibaca mesin: OpenAPI 3.1 dan Postman
Katalog di atas adalah format milik Logistivo sendiri. Informasi yang sama juga dipublikasikan dalam dua format standar industri yang sudah dipahami oleh tool Anda: definisi OpenAPI 3.1 dan koleksi Postman. Tidak satu pun ditulis tangan — keduanya dibuat dari registri perintah yang aktif pada setiap permintaan, sehingga tidak mungkin menjadi usang.
Definisi ini ADALAH katalog itu sendiri, bukan realitas kedua. Setiap perintah muncul sebagai operasi POST /api/common/commands/; schema body-nya adalah JSON Schema milik perintah itu sendiri (byte demi byte sama dengan yang dilihat asisten), schema respons-nya adalah envelope bersama, penanda gerbang (read_only, confirmation_needed, irreversible, dan badge kredit) berada di ekstensi x-logistivo, dan key error bisnis berada di bawah x-error-keys. Perintah yang dipensiunkan ditandai deprecated: true dan tetap dapat dipanggil selama jendela enam bulannya.
Di samping permukaan perintah, endpoint REST yang membawa kontrak integrasi juga ada di dalam definisi: 10 endpoint daftar dengan sinkronisasi inkremental (updated_since + cursor + limit) dan 7 endpoint tulis yang menerima key milik Anda sendiri (external_ref). Permukaan REST Logistivo jauh lebih besar dari itu; sisanya SENGAJA tidak disertakan. Payload-payload tersebut adalah kontrak milik produk itu sendiri, dan schema yang ditulis berdasarkan tebakan akan merusak klien yang Anda hasilkan pada panggilan pertama — dan Anda akan mencari bug-nya di kode Anda, bukan di kode kami.
Definisi dibuat untuk PERAN pihak yang memintanya: perintah milik peran lain tidak pernah masuk ke dokumen, karena definisi adalah kontrak, bukan kamus, dan semua yang ada di dalamnya harus dapat dipanggil dengan token tersebut. Versi tanpa autentikasi adalah gabungan dari ketiga peran, dan di sana setiap operasi menyatakan peran mana yang melihatnya di bawah x-logistivo.roles.
Jangan hanya percaya kata-kata kami — verifikasi sendiri: npx @redocly/cli lint logistivo-openapi.json lolos tanpa satu peringatan pun.
GET /api/common/spec/openapi.json — Definisi OpenAPI 3.1 untuk peran token Anda. Membawa ETag; If-None-Match memberi Anda 304, sehingga Anda tidak mengunduhnya ulang pada setiap build.
GET /api/common/spec/postman.json — Cakupan yang sama sebagai koleksi Postman v2.1, dengan variabel base_url dan token, serta folder yang sudah dikelompokkan berdasarkan domain perintah.
GET /api/public/cli/openapi.json — Versi tanpa autentikasi — gabungan dari ketiga peran. Untuk merancang dan memperkirakan biaya jembatan sebelum Anda memiliki token.
GET /api/public/cli/postman.json — Koleksi Postman tanpa autentikasi: satu file yang dapat Anda serahkan kepada tim Anda.
761 operasi — 721 perintah + 36 operasi REST dan control-plane + 4 endpoint katalog dan identitas. Angka-angka di halaman ini tidak diketik tangan; angka-angka itu dihitung dari dokumen yang aktif pada setiap permintaan, sehingga pada hari sebuah perintah dirilis, angkanya juga naik di sini — dan jumlahnya selalu cocok.
Skema keamanan — bearerAuth: token Passport yang diterbitkan untuk pengguna yang nyata. Kunci dengan scope baca hanya boleh memanggil operasi yang ditandai x-logistivo.read_only: true; upaya menulis mengembalikan 403 SEBELUM gerbang konfirmasi, sehingga kunci read-only tidak pernah melihat 409.
Setiap cabang error dituliskan — Setiap operasi menjelaskan 401/403/404/409/422/429/500 secara terpisah. Dua makna 409 (konfirmasi diperlukan / konflik idempotency) dan dua makna 422 (error schema / penolakan bisnis) dibedakan di dalam dokumen, sehingga generator Anda tidak menggabungkannya menjadi satu cabang.
Tanpa timestamp — Dokumen ini tidak membawa waktu pembuatan. Katalog yang sama menghasilkan byte yang sama, itulah sebabnya ETag benar-benar berfungsi dan definisi yang Anda commit ke version control tidak tampak 'berubah' pada setiap unduhan.
Kami tidak mengarang payload produk — Pada endpoint tulis REST, hanya field kontrak (external_ref) yang dijelaskan; sisa body tetap terbuka sebagai additionalProperties: true dan pembaca diarahkan ke dokumentasi produk. Definisi yang tidak lengkap tetapi benar lebih baik daripada definisi yang lengkap tetapi dikarang.
Daftar key error per operasi TIDAK lengkap — x-error-keys hanya mencantumkan key yang pasti mengikuti dari rekaman perintah itu sendiri, dan menyatakannya dengan x-error-keys-exhaustive: false. Kamus lengkapnya ada di root dokumen; perlakukan key apa pun yang tidak Anda kenali sebagai kegagalan umum. 'Daftar lengkap' yang dikarang akan mendorong Anda untuk tidak pernah menulis cabang default.
Tool penemuan tidak ada di dalam definisi — search_commands, run_command, dan list_capabilities hanya ada di dalam loop chat dan tidak dapat dipanggil melalui HTTP. Seandainya disertakan, generator Anda akan menulis tiga method yang tidak akan pernah berfungsi.
Pembuatan kode: klien bertipe dari definisi
Anda sudah memiliki definisinya; sekarang buat kode yang berfungsi darinya. `lg codegen` membaca dokumen OpenAPI dan menulis klien satu file tanpa dependensi — TypeScript (deklarasi tipe ditambah pembungkus panggilan yang tipis) atau PHP (kelas klien dengan array shape PHPDoc). Tanpa `npm install`, tanpa composer: `fetch` di sisi TypeScript, `ext-curl` di sisi PHP.
Pembuatan kode terjadi di mesin ANDA, bukan di server kami. Itu bukan sekadar preferensi: sematkan definisinya di repositori Anda sekali saja (`lg spec --out=...`) dan perintah yang sama berjalan pada setiap build tanpa jaringan dan tanpa token, sehingga CI Anda tidak pernah bergantung pada uptime kami. Selain itu, karena kode yang dihasilkan adalah kode yang BERJALAN di ERP Anda, menyimpannya di repositori Anda alih-alih mengambilnya dari API berarti setiap perubahan akan terlihat di `git diff`.
Klien yang dihasilkan menangani ketiga jalur Logistivo dengan benar, dan klien itu mengetahui jalur mana yang mana dari dokumen, bukan dengan menebak: setiap operasi menyatakan jalurnya di `x-logistivo.surface`. Jalur perintah membuka envelope `{success, data:{…}}`; daftar sinkronisasi REST TIDAK dibungkus envelope dan dikembalikan apa adanya (membukanya akan menghilangkan `next_cursor`); penulisan REST mengembalikan body produk milik endpoint itu sendiri. Generator serbaguna tidak mengetahui pembedaan ini — generator kami mengetahuinya.
Tipe-tipenya bukan hasil tebakan: interface argumen setiap perintah dibuat dari JSON Schema yang persis sama dengan yang dilihat asisten. Yang wajib tetap wajib, enum menjadi union type, objek bersarang menjadi tipe bersarang. Dalam praktiknya: jika server mewajibkan sebuah field, panggilan yang melupakannya tidak gagal dengan 422 di produksi — panggilan itu gagal saat kompilasi.
Tidak ada timestamp pembuatan yang ditulis ke dalam file: definisi yang sama dengan flag yang sama menghasilkan byte yang sama. Karena itu, membuat ulang klien tidak menimbulkan gangguan di `git diff`, dan satu-satunya hal yang benar-benar berubah — kontraknya — tetap terlihat.
1. Sematkan definisinya — Definisi dibuat untuk peran Anda; setiap operasi di dalamnya dapat dipanggil dengan token tersebut. Commit file-nya. lg login --api-key= lg spec --out=logistivo-openapi.json
2. Hasilkan kliennya — Satu file dihasilkan, yang memuat SETIAP operasi dalam definisi yang Anda sematkan sebagai method: perintah yang dapat dipanggil oleh peran Anda, endpoint REST yang membawa kontrak integrasi, dan endpoint penemuan. Jumlahnya adalah milik peran ANDA, bukan total platform — saat ini kunci pengirim menghasilkan 646 method perintah, pengangkut 621, agen kepabeanan 392. Jika dihasilkan dari definisi publik tanpa autentikasi, batas atasnya adalah 761 operasi. lg codegen ts --from=logistivo-openapi.json --out=logistivo-client.ts lg codegen php --from=logistivo-openapi.json --out=LogistivoClient.php --namespace="Acme\\Logistivo" # or straight from the server, without downloading first: lg codegen ts --out=logistivo-client.ts
3. Verifikasi, lalu gunakan — Jika kode yang dihasilkan tidak dapat dikompilasi, kesalahannya ada pada kami, bukan pada Anda: integritas definisi dijaga oleh pemeriksaan yang dapat dijalankan di server. npx tsc --noEmit --strict --target ES2022 --module ESNext --moduleResolution bundler logistivo-client.ts php -l LogistivoClient.php
Satu method per operasi — Setiap perintah di dalam dokumen, setiap endpoint REST yang membawa kontrak integrasi, dan endpoint penemuan. Hasilkan dari definisi peran Anda dan Anda hanya mendapatkan apa yang dapat Anda panggil (646 perintah untuk pengirim); hasilkan dari definisi publik dan Anda mendapatkan seluruh 761 operasi. Pada hari sebuah perintah ditambahkan di server, membuat ulang klien akan membawanya masuk; tidak ada rilis klien yang perlu ditunggu.
Tipe argumen — Schema `args` setiap perintah menjadi sebuah interface (array shape di PHP). Field wajib tetap wajib, enum menjadi union. Di TypeScript, melupakan field wajib adalah error kompilasi; di PHP, IDE Anda dan PHPStan melihat bentuk yang sama.
Kelas error — Taksonomi transport (`error_code`) dan taksonomi bisnis (`error_key`) adalah field yang terpisah; gerbang konfirmasi dan rate limit adalah tipe error yang terpisah. Union key error tetap terbuka untuk nilai yang tidak dikenal — ketika server mendeklarasikan key baru, kode Anda tidak berhenti dapat dikompilasi, melainkan jatuh ke cabang `default`.
Kebijakan percobaan ulang yang benar — Percobaan ulang otomatis hanya berlaku untuk panggilan yang aman: pembacaan, dan penulisan yang membawa idempotency key. Penulisan tanpa kunci yang mengalami timeout tidak berarti 'tidak ada yang ditulis', sehingga klien tidak pernah mengulanginya secara membabi buta. Pada 429, klien menunggu sesuai `Retry-After` dari server alih-alih mengarang jeda sendiri.
Body hasil tidak diberi tipe — Hasil perintah dikembalikan sebagai `unknown` (`mixed` di PHP), dengan alasan yang sama seperti pada definisinya sendiri: bentuk hasil adalah output bisnis dari perintah, bukan bagian dari kontrak. Tipe hasil yang ditebak akan mulai berbohong pada saat pertama kali sebuah field berpindah.
File yang dihasilkan tidak diedit dengan tangan — File itu adalah output, bukan sumber. Jika Anda memerlukan perilaku tambahan, bungkus kelas yang dihasilkan; apa pun yang Anda tulis di dalamnya akan hilang pada pembuatan berikutnya.
Tool penemuan tidak dihasilkan — `search_commands`, `run_command`, dan `list_capabilities` hanya ada di dalam loop chat dan tidak dapat dipanggil melalui HTTP; ketiganya tidak ada di definisi dan karena itu juga tidak ada di klien. Menyertakannya berarti menulis tiga method yang tidak pernah berfungsi.
Cakupan yang jujur
Kami lebih suka bagian ini bertambah daripada berkurang. Nilai sebuah kontrak integrasi tidak terletak pada apa yang dijanjikannya, melainkan pada seberapa jelas kontrak itu menyatakan apa yang tidak dijanjikannya.
CLI berjalan dalam konteks pengguna tenant — Setiap perintah berjalan di bawah perusahaan dan peran milik pengguna yang tokennya digunakan. Mode operator platform — mode administratif yang membaca lintas perusahaan — berada di luar permukaan ini dan tidak akan dibuka dari sini.
Daftar perintah Anda bergantung pada peran Anda — Akun pengirim melihat 646 perintah, pengangkut 621, agen kepabeanan 392, afiliasi 55. Jika sebuah perintah tidak ada di katalog Anda, periksa perannya terlebih dahulu; jika perintah itu tercantum tetapi ditolak, periksa scope dan tingkat akses kunci. Akun pengemudi sama sekali tidak memiliki akses ke permukaan ini.
Beberapa perintah memakai kredit — Pertanyaan tarif, pembuatan dokumen, dan beberapa perintah lain yang didukung AI menggunakan saldo kredit paket Anda. Setiap baris katalog membawa credit_cost {mode, credits}: fixed adalah biaya pasti per panggilan, read_only tidak pernah dikenai biaya, dan computed berarti biayanya bergantung pada panggilan — credits kemudian bernilai null dan angka sebenarnya muncul di kartu konfirmasi. Preflight (dry_run) memberi tahu Anda berapa biaya satu panggilan dan apakah saldo Anda mencukupinya.
Kunci integrasi tidak dapat mengendalikan chat dashboard — Asisten AI di dalam dashboard ditujukan untuk manusia. Memulai atau melanjutkan eksekusi asisten dengan kunci integrasi ditolak dengan 403; agen menggunakan endpoint perintah, lg, atau kanal MCP, tempat setiap perintah berjalan pada tingkat akses kunci dan penulisannya dicatat sebagai penulisan integrasi.
Katalog tidak menggantikan REST API yang sudah ada — Permukaan REST yang menjalankan aplikasi web dan seluler Logistivo tetap berada di tempatnya dan tetap tunduk pada aturan kompatibilitas mundur. Katalog perintah tidak menggantikan CRUD sumber daya; katalog ini adalah lapisan VERB — satu-satunya cara yang teraudit untuk melakukan sesuatu.
Perintah daftar saat ini mengembalikan jendela kecil — Sampai sebuah perintah daftar mencantumkan cursor dan updated_since di schema-nya, batas atasnya adalah 20 baris tanpa cursor. Perintah daftar tidak dirancang untuk mengekstrak salinan lengkap data Anda; sinkronisasi inkremental diterapkan secara bertahap, perintah demi perintah.
Pertanyaan yang sering diajukan
Untuk apa Logistivo CLI digunakan?
CLI ini menjalankan pekerjaan di akun Logistivo Anda dari terminal, skrip, atau agen AI Anda sendiri: muatan dan perjalanan, permintaan angkutan, penawaran dan tender, armada, pengemudi beserta pengeluaran mereka, dokumen, kontak dan rekening berjalan, faktur dan akuntansi, gudang dan stok, anggota tim, tarif HS, dan bea antidumping. Setiap tindakan tulis di panel memiliki perintah; pembayaran, persetujuan hukum, dan penutupan akun sengaja tetap di browser. Perintah yang sama dapat dipanggil melalui HTTP untuk integrasi ERP/CRM dan melalui kanal MCP.
Bagaimana perintah diberi nama di Logistivo CLI?
Bentuknya adalah lg --parameter=value. Domain adalah entitas dalam bentuk jamak (loads, demands, invoices, export-documents) dan verb berasal dari kosakata tertutup yang hanya bertambah melalui keputusan yang disengaja (list, get, create, update, search, set-status, generate, dan seterusnya). Semua verb dari satu entitas berada dalam satu domain, dan pasangan (domain, verb) unik di seluruh katalog.
Bagaimana cara saya melakukan autentikasi ke CLI?
Secara interaktif, lg login menampilkan kode persetujuan yang Anda konfirmasi di browser setelah masuk ke Logistivo — tidak ada kata sandi atau kunci yang diketik di terminal, dan sesi tetap dalam keadaan masuk serta memperbarui dirinya sendiri sampai Anda menjalankan lg logout. lg login --password (email dan kata sandi) tetap tersedia sebagai cadangan. Di server dan di CI, gunakan kunci integrasi yang diterbitkan di panel atau dengan lg keys create: lg login --api-key menyimpannya ke profil lokal, atau taruh kunci itu di variabel lingkungan LOGISTIVO_TOKEN. Melalui HTTP, token dikirim di header Authorization: Bearer.
Dapatkah saya membuat akun layanan untuk integrasi ERP saya?
Tidak. Sebuah integrasi terhubung dengan token milik pengguna perusahaan yang nyata yang dibuat di panel. Identitas sintetis tanpa perusahaan membuat isolasi multi-tenant tidak berfungsi, membuat kolom "siapa yang menjalankan ini" di log audit tidak bermakna, dan meninggalkan jembatan yang tidak berhenti ketika pemiliknya keluar. Pola yang benar adalah pengguna khusus dengan peran yang sempit dan pemilik yang disebut namanya.
Apakah Logistivo memiliki lingkungan uji (sandbox)?
Ya, dan dapat dibuka secara mandiri: tenant sandbox terpisah dibuka untuk perusahaan Anda — kode yang sama, katalog perintah yang sama, ledger kredit tersendiri. Lingkungan ditentukan dari perusahaan pemilik kunci dan tidak dapat disertakan dalam permintaan; panggilan yang dibuat dengan profil yang salah akan berhenti di sisi server dengan 403 ENVIRONMENT_MISMATCH. Permintaan angkutan yang Anda buka di sandbox tidak pernah sampai ke pengangkut sungguhan, event sandbox tidak pernah dikirim ke langganan webhook live Anda, dan saldo live Anda tidak bergerak. Endpoint: POST /api/common/integration-sandbox (membuka), POST /api/common/integration-sandbox/keys (kunci), GET /api/common/integration-sandbox/go-live (daftar periksa go-live). Di sisi lg, lg --sandbox dan lg --live adalah pemilih profil untuk satu kali eksekusi.
Bagaimana cara membaca output lg --json dalam skrip?
Output-nya adalah seluruh envelope HTTP: { "success": bool, "data": { "contract_version", "command", "status", "result" }, "code", "message" }. Payload bisnis berada di bawah .data.result; pada perintah daftar, barisnya adalah .data.result., jumlahnya .data.result.count, dan halaman berikutnya .data.result.next_cursor. Jadi, path jq yang benar terlihat seperti lg loads list --json | jq -r '.data.result.loads[].load_code'. Path yang melewati envelope tidak menghasilkan error, tetapi diam-diam mengembalikan null — dalam skrip watchdog, hal itu menjadi alarm yang tidak pernah berhenti berbunyi. Satu-satunya pengecualian adalah /api/public/status, yang body-nya sengaja tidak memakai envelope.
Jika saya mengirim permintaan yang sama dua kali, apakah saya akan mendapat rekaman ganda?
Tidak, jika Anda mengirim idempotency_key. Panggilan kedua dengan kunci yang sama tidak menjalankan ulang perintah; panggilan itu mengembalikan hasil pertama dengan status replayed. Kunci sebaiknya berupa UUID dan harus tetap SAMA di setiap percobaan ulang — membuat kunci baru untuk setiap percobaan sama saja dengan tidak menggunakan idempotency.
Apa fungsi --yes?
Flag ini melewati gerbang konfirmasi. Ketika perintah yang dijaga gerbang dipanggil tanpa --yes, tidak ada yang berubah: server merangkum dalam satu kalimat apa yang akan dilakukannya, menyatakan apakah tindakan itu tidak dapat dibatalkan, lalu berhenti (HTTP 409, kode keluar CLI 4). Mengulangi perintah dengan --yes akan menjalankan pekerjaannya.
Bagaimana cara mendeteksi perintah yang gagal dalam skrip?
Baca kode keluarnya, jangan pernah teks pesannya: 0 berhasil, 1 penolakan aturan bisnis, 2 error perintah atau argumen, 3 error autentikasi atau peran, 4 konfirmasi diperlukan. Melalui HTTP, padanannya adalah 200, 422, 404, 403, dan 409, dan field error_code di body bersifat stabil. PESAN error dilokalkan dan berubah tanpa pemberitahuan.
Bagaimana cara menemukan perintah yang tersedia secara terprogram?
GET /api/public/cli/catalog untuk penemuan tanpa autentikasi, dan GET /api/common/commands untuk daftar yang benar-benar dapat dilihat oleh akun Anda. Keduanya mengembalikan parameter JSON Schema setiap perintah; bangun klien Anda dari parameter tersebut alih-alih menulis daftar perintah secara hard-code.
Apakah saya harus memperbarui klien saya ketika perintah baru ditambahkan?
Tidak. Klien mengambil daftar perintahnya dari katalog, sehingga perintah yang ditambahkan di server akan muncul tanpa rilis klien baru. Pembaruan hanya diperlukan untuk perubahan yang merusak kompatibilitas yang menaikkan versi kontrak, dan dalam hal itu bentuk lama tetap hidup paling sedikit enam bulan.
Apakah CLI menggantikan REST API yang sudah ada?
Tidak. Permukaan REST yang menjalankan aplikasi web dan seluler tetap di tempatnya. Katalog perintah tidak menggantikan CRUD sumber daya; katalog ini adalah lapisan verb — satu-satunya cara yang dijaga gerbang peran, dijaga gerbang konfirmasi, dan teraudit untuk melakukan sebuah tindakan.
Bagaimana cara mendapatkan kunci API Logistivo dan apa yang dapat dilakukannya?
Manager dengan izin pengelolaan tim menerbitkannya di panel di bawah Settings › Integration keys, atau dari terminal dengan lg keys create. Kunci bertindak atas nama anggota tim yang nyata dan memiliki tiga pengaturan yang independen: scope (read membuka katalog dan perintah yang tidak menulis, write membuka setiap perintah — gerbang konfirmasi tetap seperti apa adanya), pemberian akses domain yang opsional, dan tingkat akses — employee, bawaannya, untuk operasi sehari-hari, atau manager untuk tim, pengaturan, kunci, dan uang. Kunci ditampilkan satu kali dan tidak disimpan di server; kunci dapat dirotasi, ditransfer, dan dicabut. Ketika anggota yang diwakilinya keluar, kunci itu juga ditutup. Tidak ada akun layanan.
Apa yang terjadi jika saya memakai ulang idempotency key untuk perintah yang berbeda?
Server menjawab 409 idempotency_conflict dan menyebutkan perintah yang pertama kali menggunakan kunci tersebut; tidak ada yang dijalankan dan tidak ada yang diputar ulang. Kunci dibatasi pada perusahaan Anda, terikat pada satu perintah, dan dikunci selama 24 jam — setelah itu, kunci yang sama memulai eksekusi baru.
Bagaimana rate limit diterapkan pada integrasi saya?
Per token, per menit, dalam tiga bucket: pembacaan katalog 120, perintah baca 120, perintah tulis 30. Respons 429 selalu membawa Retry-After dan body dengan retry_after, limit, dan bucket; tunggu selama itu lalu coba lagi. Katalog memublikasikan angka-angka terkini di bawah rate_limits.
Bagaimana cara membedakan penolakan bisnis dari error transport?
Buat percabangan berdasarkan error_code terlebih dahulu: failed (422) adalah penolakan bisnis dan membawa error_key yang stabil seperti INSUFFICIENT_CREDITS atau NOT_FOUND; server_error (5xx) dan error jaringan dicoba ulang dengan idempotency key yang sama; rate_limited (429) ditunggu hingga berlalu. Jangan pernah membuat percabangan berdasarkan teks error.
Apakah Logistivo mengirim webhook? Untuk event apa saja?
Ya. Anda mendaftarkan alamat https dan memilih event yang Anda pedulikan; sebuah POST bertanda tangan tiba ketika event itu terjadi. Saat ini 13 event dapat dilanggani: muatan dibuat/status berubah/pengemudi ditugaskan, permintaan angkutan dibuat dan status berubah, penawaran diajukan/direvisi/diterima, faktur draf/diterbitkan/dibatalkan, dan reservasi gudang dibuat/status berubah. Setiap nama didukung oleh kelas event yang benar-benar di-dispatch — tidak ada yang diumumkan lalu tidak pernah dipicu, karena event seperti itu adalah kegagalan senyap yang ditunggu integrator selamanya. Langganan dibuat di bawah Settings › Integration › Webhooks, atau dari terminal dengan lg webhooks create.
Bagaimana cara memverifikasi tanda tangan webhook Logistivo?
Setiap permintaan membawa header X-Logistivo-Signature: t=,v1=. String yang ditandatangani adalah ".", algoritmanya HMAC-SHA256, dan kuncinya adalah secret langganan. Empat aturan: (1) verifikasi byte MENTAH — men-decode lalu menserialisasi ulang body (JSON.stringify / json_encode) mengubah data yang sama menjadi byte yang berbeda dan tanda tangannya tidak lagi cocok; inilah kesalahan paling umum; (2) periksa timestamp dan buang apa pun dengan |now − t| > 300 s meskipun tanda tangannya benar; (3) bandingkan dalam waktu konstan dengan hash_equals / timingSafeEqual; (4) lakukan deduplikasi berdasarkan event_id, bukan id pengiriman — event_id dipertahankan saat replay sementara id pengiriman berubah. Penerima Node dan PHP yang berfungsi tersedia di examples/webhook-receiver/ di repositori dan menguji dirinya sendiri dengan --selftest.
Apa yang terjadi jika webhook tidak dapat dikirim? Apakah saya kehilangan event-nya?
Tidak. Jika penerima Anda tidak mengembalikan 2xx, pengiriman masuk ke jadwal percobaan ulang: 60 · 300 · 1800 · 7200 · 21600 detik, total 6 percobaan, jendela waktu sekitar 8,6 jam. SETIAP kegagalan kecuali 410 Gone dicoba ulang, termasuk 4xx — kehilangan event bisnis lebih mahal daripada beberapa permintaan tambahan. Setelah 10 pengiriman berturut-turut yang kehabisan percobaan, langganan dinonaktifkan dan alasannya dicatat, sehingga pertanyaan "mengapa tidak ada yang masuk" tetap dapat dijawab. Ledger pengiriman menyimpan setiap percobaan (kode status, durasi, error) dan Anda dapat mengirim ulang satu pengiriman dari panel atau dengan lg webhooks replay. Sinkronisasi inkremental (updated_since + cursor) tetap ada sebagai jaring pengaman.
Dapatkah agen AI saya melakukan semua yang dapat dilakukan pengguna di panel?
Hampir semuanya. Setiap tindakan tulis di panel memiliki perintah — diukur terhadap endpoint tulis panel, 100% endpoint yang termasuk dalam cakupan sudah tercakup — dan perintah yang sama terbuka untuk lg, untuk HTTP, dan untuk kanal MCP. Pengecualian yang disengaja adalah langkah-langkah yang menyangkut identitas dan uang: masuk (sign-in), membeli paket, menambahkan kartu dengan 3D Secure, menyetujui teks hukum, dan menutup akun tetap berada di browser milik orang itu, dan lg handoff-links generate mengembalikan tautan untuk langkah-langkah tersebut. Kunci integrasi, webhook, dan sandbox dikelola dengan perintah bawaan lg karena semuanya mengembalikan secret satu kali.
Dapatkah saya meneruskan file seperti PDF atau foto ke perintah dari CLI atau API?
Ya. Dengan lg, tambahkan @ di depan path lokal (--attachment_uuid=@./cmr.pdf) dan lg akan mengunggah file tersebut terlebih dahulu; --file adalah jalan pintas ketika sebuah perintah hanya memiliki satu field file, dan lg upload hanya melakukan pengunggahan. Melalui HTTP, kirim file sebagai multipart ke POST /api/common/commands:upload lalu teruskan attachment_uuid yang dikembalikan ke perintah; klien MCP menggunakan tool upload_attachment. Tipe file dideteksi dari isinya, unggahan adalah milik pengguna dan tetap dapat digunakan selama 24 jam, dan mengunggah file yang sama sekali lagi mengembalikan id yang sama.
Apa perbedaan antara kunci integrasi employee dan manager?
Tingkat akses menentukan seberapa berat pekerjaan yang boleh dilakukan sebuah kunci. Kunci employee, bawaan untuk kunci baru, menjalankan operasi sehari-hari: muatan, permintaan angkutan, penawaran, perjalanan, armada, dokumen, dan kontak. Kunci manager juga boleh melakukan pekerjaan manajemen — anggota tim dan peran, pengaturan perusahaan, kunci integrasi, rekening bank, kartu tersimpan, pembayaran afiliasi. Sebuah kunci tidak pernah memiliki hak lebih banyak daripada orang yang diwakilinya, dan kunci employee yang memanggil perintah manager mendapat INSUFFICIENT_KEY_LEVEL. Ubah tingkatnya di panel atau dengan lg keys update --access-level=manager.
Dapatkah afiliasi (mitra rujukan) menggunakan CLI?
Ya. Akun afiliasi mendapat katalognya sendiri — 55 perintah untuk rujukan, prospek (lead), catatan dan tugas CRM, materi presentasi penjualan, pendapatan, dan pembayaran — dan menggunakannya dari lg, HTTP, atau MCP seperti peran lainnya. Meminta atau membatalkan pembayaran serta mengubah rekening bank untuk pembayaran memerlukan kunci tingkat manager dan konfirmasi. Perusahaan yang juga merupakan pengirim, pengangkut, atau agen kepabeanan melihat kedua katalog.
For AI assistants
Logistivo has an MCP server at https://logistivo.com/api/agent/mcp
(streamable HTTP). Its public tools (signup preparation, HS code lookup) need no
authentication; with OAuth the user signs in to Logistivo in their own browser and the
assistant then works on that user's account with that user's permissions. Setup for
Claude, ChatGPT and Gemini: https://logistivo.com/en/mcp.
Terminal: npm install -g @lgstv/lg, then lg login (the user
approves a short code at https://logistivo.com/connect; no password is typed into the
terminal). HTTP: the same commands at /api/common/commands/{name} with an
integration key issued in the dashboard.
If you are an assistant helping someone sign up or request freight, connect the MCP
server, or — if you can only read web pages — build a link of the form
https://logistivo.com/en/ai-kayit?brief=URL_ENCODED_SHIPMENT_BRIEF and give
it to the user. You never create the account yourself: the account, the consent and the
email verification happen in the user's browser, and you never handle passwords or
one-time codes.
Machine-readable content indexes:
https://logistivo.com/llms.txt (curated map) and
https://logistivo.com/llms-full.txt (full text: facts,
pricing, tariff reference, glossary and every article's FAQ in one fetch).
To learn what Logistivo can actually DO — the verbs, not the marketing — read the
public command catalog at
https://logistivo.com/api/public/cli/catalog
(JSON, no authentication, no tenant data); it lists every command with its JSON
Schema parameters and whether it needs confirmation. Human documentation:
https://logistivo.com/en/developers/cli. Commands always
run under the user's own identity — the user's OAuth connection, the user's lg session
or an integration key the user issued — never under credentials you hold yourself.