Logistivo CLI: prowadź operacje logistyczne z terminala i ze swojego ERP
Jeden katalog poleceń zasila trzy powierzchnie: terminalowego klienta lg, asystenta AI w panelu oraz kanał, przez który łączą się zewnętrzni asystenci AI. Funkcję pisze się raz i pojawia się ona we wszystkich trzech miejscach — a każda operacja zapisu w panelu ma już swoje polecenie, więc twoje skrypty i twoi własni agenci AI mogą wykonywać pracę, którą twój zespół wykonuje na ekranie. Płatności, zgody prawne i zamknięcie konta celowo pozostają w przeglądarce. Ta strona jest kontraktem. Poniższa tabela poleceń nie jest pisana ręcznie; jest generowana z bieżącego rejestru poleceń przy każdym żądaniu.
Czym jest Logistivo CLI?
Logistivo CLI (lg) to klient wiersza poleceń, który wykonuje pracę na twoim koncie Logistivo — ładunki i kursy, zapytania transportowe, oferty i przetargi, flota i kierowcy, dokumenty, kontakty i rozrachunki, faktury i księgowość, magazyn i stany magazynowe, członkowie zespołu oraz taryfy celne — z terminala, ze skryptu lub z twojego własnego agenta AI. Polecenia nie są wbudowane w klienta: klient pobiera katalog poleceń z serwera i na jego podstawie sam się rysuje. Te same polecenia można wywołać przez HTTP bez instalowania czegokolwiek — tej drogi używają integracje ERP i CRM — oraz przez kanał MCP, z którym łączą się zewnętrzni asystenci AI.
Jeden kształt polecenia: lg --parameter=value. Katalog składa się dziś z 721 poleceń w 175 domenach; najszersza lista, jaką widzi pojedyncza rola, składa się z 646 poleceń w 165 domenach.
Każda operacja zapisu w panelu ma swoje polecenie — w pomiarze względem endpointów zapisu panelu pokrytych jest 100% endpointów objętych zakresem. Płatności (3D Secure), zgody prawne i zamknięcie konta celowo pozostają w przeglądarce; w tych przypadkach polecenie zwraca zamiast tego link.
Polecenia przyjmujące dokument lub zdjęcie działają także poza przeglądarką: napisz --attachment_uuid=@./cmr.pdf, a lg najpierw prześle plik; przez HTTP przesyłasz plik do /api/common/commands:upload i przekazujesz zwrócony attachment_uuid.
Klucze integracyjne mają poziom dostępu: employee (domyślny dla nowych kluczy) do codziennych operacji, manager do spraw zespołu, ustawień, kluczy i pieniędzy. Klucz nigdy nie ma większych uprawnień niż osoba, w imieniu której działa.
Flagi nigdy nie są wymyślane: każda flaga to nazwa parametru z własnego JSON Schema polecenia — stamtąd pochodzą też jej typ i informacja, czy jest wymagana.
Polecenia zapisujące proszą o potwierdzenie; nieodwracalne nigdy nie wykonują się bez niego (HTTP 409, kod wyjścia CLI 4).
Ponawianie nie tworzy duplikatów: wywołanie z idempotency_key wykonuje się najwyżej raz.
Każde wykonanie trafia do jednego rejestru audytu — w zapisie widać, czy pochodziło z terminala, z czatu, czy od asystenta.
Co działa dziś, a co jest w drodze
Ta sekcja celowo znajduje się na górze strony. Najdroższy błąd, jaki może popełnić dokument integracyjny, to opisanie endpointu, który nie jest jeszcze otwarty, tak jakby już działał: integrator pisze kod, endpoint zwraca 404, a zaufanie już nie wraca.
Ponieważ kontrakt jest zamrożony, kod integracji, który piszesz dziś, będzie działał dalej, gdy otworzą się pozostałe elementy. Pola, których nie znasz, musisz ignorować; to właśnie ta reguła pozwala nam dodawać bez psucia.
Katalog poleceń i tabela tożsamości — Publiczna tożsamość domena/czasownik każdego polecenia jest zamrożona, a wersja kontraktu jest publikowana jako 1 w każdej odpowiedzi katalogu oraz w nagłówku X-Contract-Version. Tabela na tej stronie jest generowana z bieżącego rejestru: polecenie dodane na serwerze pojawia się tu samo, a usunięte znika.
Endpoint wykrywania bez uwierzytelnienia — GET /api/public/cli/catalog — nazwy poleceń, tożsamość domena/czasownik, opis, parametry JSON Schema, flagi bramek i pola wersjonowania (since, deprecated_at, replaced_by, aliases). Bez uwierzytelnienia: wygenerowanie tokenu to krok, który następuje PO decyzji o integracji, a nie przed nią. Odpowiedź nie zawiera żadnych danych tenanta (firmy-klienta platformy).
Uwierzytelnione endpointy katalogu i wykonania — GET /api/common/commands, GET /api/common/commands/{name} oraz POST /api/common/commands/{name}. Bramka ról, bramka potwierdzenia, idempotencja i rejestr audytu działają w jednym punkcie egzekwowania, przez który przechodzą również czat i terminal.
Pokrycie panelu: każda operacja zapisu ma polecenie — Katalog z 721 poleceniami w 175 domenach sprawdzono względem endpointów zapisu panelu: za każdym endpointem objętym zakresem stoi polecenie (lustro endpointu lub ta sama współdzielona usługa) i żaden nie pozostaje niepotwierdzony. Celowo poza zakresem: płatności z 3D Secure, zgody prawne, zamknięcie konta i logowanie, które pozostają w przeglądarce; zarządzanie kluczami, webhookami i sandboxem, które są wbudowanymi poleceniami lg; oraz własne endpointy aplikacji kierowcy.
Przebieg próbny (dry_run): zobacz efekt bez uruchamiania — Z dry_run: true w treści żądania polecenie się nie wykonuje: walidacja, bramka ról/zakresu, rozpoznanie celu i wyliczenie kredytów są wykonywane i wraca podgląd; nic nie zostaje zapisane, żaden kredyt nie jest zużywany, a klucz idempotencji nie zostaje skonsumowany. Endpoint wsadowy (batch) również to przyjmuje — dla całego wsadu. Przebieg próbny nigdy nie wchodzi do handlera polecenia; przy wdrożeniu 178 przebiegów próbnych na wszystkich ówczesnych poleceniach zapisu w katalogu nie wygenerowało ani jednej instrukcji zapisu.
Klucze integracyjne — Klucze API działające w imieniu prawdziwego członka zespołu, wydawane w panelu lub poleceniem lg keys create: zakres odczyt/zapis, poziom dostępu (domyślnie employee albo manager), okres ważności, ostatnie użycie, rotacja, przeniesienie i unieważnienie. Na nich oparte są lg login --api-key, lg whoami oraz lg logout, który unieważnia klucz po stronie serwera.
Sandbox — przećwicz zapisy bez dotykania produkcji — Osobny tenant sandbox dla każdej firmy, z tym samym katalogiem poleceń; otwierany samoobsługowo, wydaje własny klucz. Kredyty, marketplace i routing webhooków są rozdzielone między dwa środowiska; środowisko wynika z firmy, do której należy klucz, i nie można go podać w żądaniu.
Wersjonowanie, taksonomia błędów, idempotencja i limity żądań — Polecenia mają pola since / deprecated_at / replaced_by / aliases, a wycofywane polecenie odpowiada z nagłówkiem X-Deprecated. Błędy biznesowe niosą stabilny error_key obok error_code z warstwy transportowej, a słownik kluczy jest publikowany w katalogu. Klucze idempotencji są ograniczone do twojej firmy, powiązane z jednym poleceniem i blokowane na 24 godziny. Limity żądań (rate limits) działają per token, w trzech pulach, a każda odpowiedź 429 zawiera Retry-After.
Webhooki wychodzące: POST, gdy coś się wydarzy — Podpisany push działa dla 13 zdarzeń. Subskrypcjami zarządzasz w panelu lub poleceniem lg webhooks; podpis zawiera własny znacznik czasu, harmonogram ponowień to 60 · 300 · 1800 · 7200 · 21600 s, a powód wyciszenia jest zawsze zapisywany. Za każdą nazwą zdarzenia stoi klasa zdarzenia, która jest faktycznie wysyłana — nic nie jest ogłaszane, by potem nigdy nie zostać wysłane. Kanał pull (updated_since + cursor) nie został usunięty: push dodano obok niego, a nie zamiast niego.
Polecenia przyjmujące pliki — Do 38 poleceń przekazujesz dokument lub zdjęcie — CMR, fakturę, dowód rejestracyjny pojazdu, zdjęcia palet. Prześlij plik raz do POST /api/common/commands:upload albo pozwól, by zrobił to lg z --attachment_uuid=@./file.pdf, i przekaż zwrócony attachment_uuid; klienci MCP używają narzędzia upload_attachment. Typ pliku jest rozpoznawany na podstawie zawartości, a przesłany plik pozostaje użyteczny przez 24 h.
Klient terminalowy lg — Opublikowany w npm na licencji MIT: zainstaluj przez `npm install -g @lgstv/lg` albo uruchom bez instalacji przez `npx @lgstv/lg`. To jeden plik bez zależności, a ponieważ powierzchnia HTTP jest otwarta, możesz zintegrować się bez niego. Loguje się kodem zatwierdzenia, który potwierdzasz w przeglądarce, a potem pozostaje zalogowany i sam odnawia swoją sesję; przesyła za ciebie lokalne pliki (@path, --file, lg upload), zarządza kluczami integracyjnymi (lg keys), nigdy nie przyjmuje sekretu w wierszu poleceń, respektuje Retry-After, ponawia 5xx z tym samym kluczem idempotencji i ostrzega o wycofywanych poleceniach oraz nowszych wersjach kontraktu.
Synchronizacja przyrostowa: paginacja kursorem i updated_since — Poniższy kontrakt (limit + nieprzezroczysty, podpisany cursor, next_cursor, updated_since) jest ustalony i jest wdrażany w poleceniach listujących. Dopóki dane polecenie listujące nie ogłosi cursor i updated_since w swoim JSON Schema, traktuj je jako małe okno: maksymalnie 20 wierszy, bez kursora.
Co tu jest inaczej: klient nie zna poleceń, tylko je rysuje
To jedna decyzja, która nadaje sens reszcie tej strony. W zwykłym CLI polecenia mieszkają w kliencie; w Logistivo mieszkają na serwerze.
W klasycznym układzie, gdy serwer zyskuje nową funkcję, klient potrzebuje nowego wydania, a użytkownik musi je zainstalować. W międzyczasie obie strony wiedzą co innego — i to jest najcichszy tryb awarii w integracjach: skrypt działa, kod wyjścia to 0, a polecenie po prostu nie opisuje tego, co potrafi serwer.
W Logistivo definicja polecenia to jeden rekord: nazwa, co robi, parametry JSON Schema, które role mogą je widzieć, czy wymaga potwierdzenia i czy jego efekt jest odwracalny. Przy starcie lg pobiera ten katalog i generuje z niego tekst pomocy, flagi i walidację danych wejściowych. W chwili, gdy polecenie zostaje dodane na serwerze, lg je zna — bez aktualizacji klienta.
Ten sam katalog zasila asystenta AI w panelu oraz kanał, z którym łączą się zewnętrzni asystenci AI. Funkcję pisze się raz, a pojawia się w trzech miejscach — i wszystkie trzy przechodzą przez tę samą bramkę ról, tę samą bramkę potwierdzenia i ten sam rejestr audytu. Nie istnieje osobny spis poleceń CLI; gdyby istniał, te trzy powierzchnie po cichu rozjechałyby się w ciągu sześciu miesięcy.
Brak rozjazdu wersji — Lista poleceń, którą zna klient, jest z definicji listą, którą ma serwer. Pytanie „W której wersji lg jest to polecenie?” po prostu nie istnieje.
Nazwy flag nigdy nie są zgadywane — Flagi polecenia to dokładnie nazwy parametrów w jego JSON Schema. Aby dowiedzieć się, co polecenie przyjmuje, nie czytasz dokumentu, tylko katalog — a katalog jest zawsze aktualny.
Twoje CLI jest tak duże jak twoje konto — Katalog jest filtrowany według ról: polecenie, którego twoja rola nie widzi, nigdy nie pojawia się na twojej liście. Konto przewoźnika ma dostęp do 621 poleceń, konto nadawcy — do 646, agencji celnej — do 392, a konto afilianta (partnera polecającego) — do własnego zestawu z 55 poleceń.
Dokumentacja nie może zostać w tyle — Tabela poleceń na tej stronie pochodzi z tego samego rejestru. Nigdzie nie ma listy, którą człowiek musiałby synchronizować z rzeczywistością.
Reguła nazewnictwa — jak rosną nazwy poleceń
Katalog będzie rósł. Nowe polecenia nie są nazywane doraźnie; obowiązuje sześć reguł. Publikujemy je tutaj, bo to nazwy, które twoja integracja będzie pisać przez lata, a ich przewidywalność ma dla ciebie wartość.
Domena to encja w liczbie mnogiej — loads, demands, invoices, export-documents. Domeny dwuwyrazowe zapisuje się w kebab-case. Jedynym wyjątkiem jest rzeczownik niepoliczalny: stock nigdy nie występuje w liczbie mnogiej, bo „stocks” oznacza coś innego.
Wszystkie czasowniki jednej encji mieszkają w jednej domenie — loads zawiera każdy czasownik działający na ładunku: create, list, get, update, set-status, assign-driver, list-problems, archive i więcej. Otwieranie nowej domeny dla każdego czasownika (load-statuses, load-drivers) zmuszałoby użytkownika do szukania tej samej encji w trzech miejscach.
Czasownik nigdy nie przecieka do domeny; domena to to, co się ZMIENIA — Przypisanie kierowcy zmienia ładunek, a nie kierowcę, więc jest to lg loads assign-driver. Dopełnienie (-driver) dołącza się do czasownika, nigdy do domeny.
Zasób podrzędny nigdy nie dostaje własnej domeny — Pozycji faktury ani pozycji dokumentu nie da się wylistować samodzielnie; adresuje się je przez ich właściciela — lg invoices add-line, lg export-documents add-item. Rozstrzyga jeden test: jeśli nie możesz wylistować ani pobrać czegoś niezależnie, to nie jest domena.
Zawężenie to flaga, a nie nowy czasownik — lg fleet-documents list --days=30 jest poprawne; nie ma osobnego czasownika „list-expiring”, bo okno jest już parametrem. Czasownika kwalifikowanego używa się tylko wtedy, gdy zwracane wiersze nie są encją domeny: loads list-problems zwraca flagi problemów, a nie ładunki.
Para (domena, czasownik) jest unikalna w całym katalogu — Nawet dla dwóch poleceń, których role nigdy się nie pokrywają. Gdyby ta sama para została nadana dwóm poleceniom, twój kod integracji patrzyłby na jedną nazwę, podczas gdy CLI uruchamiałoby różne rzeczy w zależności od tego, kto je wywołał.
Pokrycie: wszystko z panelu dostępne poleceniem
Wiele zespołów podłącza Logistivo do własnego agenta AI lub środowiska automatyzacji, a agent jest użyteczny tylko wtedy, gdy potrafi dokończyć zadanie. Zasada jest więc prosta: wszystko, co użytkownik biurowy może zmienić w panelu, może zmienić także polecenie — za tą samą bramką ról, tą samą bramką potwierdzenia i z tym samym rejestrem audytu.
To jest zmierzone, a nie deklarowane. Każdy endpoint zapisu stojący za panelem jest sprawdzany względem rejestru poleceń, a endpoint uznaje się za pokryty tylko wtedy, gdy polecenie deklaruje go jako swoje lustro HTTP lub wywołuje tę samą współdzieloną usługę. Spośród endpointów zapisu objętych zakresem pokrytych jest 100%, a żaden nie pozostaje niepotwierdzony. Każdy pominięty endpoint ma spisany powód — kroki tożsamości i płatności, płaszczyzna sterowania integracją, własne endpointy aplikacji kierowcy, telemetria klienta, martwe kopie bez wywołujących — a te, które mają znaczenie dla integratora, są wymienione poniżej.
Polecenia przyjmujące plik podlegają tej samej zasadzie: do 38 poleceń w tabeli przekazujesz dokument lub zdjęcie i wszystkie działają z lg, przez HTTP i przez MCP (zob. Polecenia przyjmujące pliki).
Prace zarządcze również są pokryte, za mocniejszym kluczem: klucz integracyjny na poziomie manager jest potrzebny do 87 poleceń w tabeli — członkowie zespołu i role, ustawienia firmy, konta bankowe, zapisane karty, klucze integracyjne. Klucz na poziomie employee, domyślny, wykonuje codzienne operacje i przy tych poleceniach dostaje odmowę z INSUFFICIENT_KEY_LEVEL.
Konta afiliantów (partnerów polecających) mają własny katalog z 55 poleceniami w 20 domenach — rekomendacje (referrals), leady, notatki i zadania CRM, prezentacje sprzedażowe, zarobki i wypłaty oraz polecenia konta i zespołu, które ma każda rola. Polecenia dostępne tylko dla afiliantów nie są w publicznej tabeli poniżej, która obejmuje trzy role panelu; konto afilianta widzi je w GET /api/common/commands i w lg commands. Firma, która jest jednocześnie afiliantem oraz nadawcą, przewoźnikiem lub agencją celną, widzi oba zestawy.
Agent powinien zacząć od lg users get (nazwa API get_current_user): zwraca rolę, poziom dostępu używanego klucza, efektywne uprawnienia oraz informację, czy oczekująca akceptacja prawna lub niezweryfikowany numer telefonu blokują obecnie zapisy — dzięki temu agent może przewidzieć odmowę, zamiast ją zbierać.
Pokrycie jest mierzone raportem, który porównuje rejestr poleceń z endpointami zapisu panelu; endpoint panelu dodany bez polecenia pojawia się w nim jako niepotwierdzony. Jeśli znajdziesz w panelu działanie, do którego nie da się dotrzeć poleceniem, zgłoś to do wsparcia.
1. Poproś o link — Praca, która musi odbyć się we własnej sesji przeglądarki danej osoby, nie jest poleceniem, ale powierzchnia poleceń o niej wie. lg handoff-links generate (nazwa API get_browser_handoff_link) zwraca link do logistivo.com dla celów, na które pozwala twoja rola: package_purchase, payment_cards, legal_documents, integration_keys, affiliate_demo_accounts i account_close. Jest bezpłatne, niczego nie zapisuje, a link nie zawiera żadnego sekretu — osoba loguje się jak zwykle.
2. Przekaż go osobie — Pokaż link użytkownikowi lub wyślij go własnym kanałem. Użytkownik kończy tam krok: akceptację umowy i płatność 3D Secure za pakiet, dodanie karty, akceptację oczekujących tekstów prawnych, wydanie klucza API, którego sekret jest pokazywany raz, albo zamknięcie własnego konta.
3. Odczytaj wynik poleceniem — Po wykonaniu kroku jego wynik jest znów widoczny dla poleceń: pakiet i saldo kredytów, zapisana karta (zamaskowana, tylko cztery ostatnie cyfry), nowy klucz na liście kluczy. Agent nigdy nie przyjmuje w czacie numeru karty, płatności ani zgody.
Płatności i 3D Secure — Zakup lub podniesienie pakietu oraz dodanie karty wymagają 3D Secure w przeglądarce. Polecenia wyświetlają pakiety i ceny, odczytują saldo i jego historię, wyświetlają zapisane karty (zamaskowane), ustawiają domyślną kartę i usuwają kartę; sam zakup przechodzi przez link przekazania.
Zgody prawne — Akceptacji tekstów prawnych dokonuje osoba, w przeglądarce. lg users get mówi ci, że akceptacja oczekuje; żadne polecenie nie może jej udzielić.
Zamknięcie konta, logowanie i hasło — Zamknięcie własnego konta, logowanie i zmiana hasła to kroki tożsamości i pozostają w przeglądarce. lg user-accounts preview pokazuje, co oznaczałoby zamknięcie konta, bez wykonywania go.
Klucze integracyjne, webhooki i sandbox — Zarządzanie nimi zwraca sekrety, które muszą zostać pokazane raz, w twoim terminalu, dlatego są to wbudowane polecenia lg (lg keys, lg webhooks, lg sandbox) działające na własnych endpointach HTTP, a nie polecenia katalogu. Katalog zawiera tylko dwa polecenia kluczy bez sekretów: integration-keys list i integration-keys revoke.
Czat asystenta w panelu — Klucze integracyjne nie mogą sterować czatem asystenta AI w panelu; rozpoczęcie lub kontynuowanie sesji kluczem dostaje odpowiedź 403. Agent łączy się zamiast tego przez endpointy poleceń, lg lub kanał MCP — tam każde polecenie działa na poziomie dostępu klucza, a jego zapisy są rejestrowane jako zapisy integracyjne.
Aplikacja kierowcy — Konta kierowców nie mają katalogu poleceń, a aplikacja kierowcy zachowuje własne endpointy. Użytkownicy biurowi zarządzają kierowcami, ich dokumentami, wydatkami i kursami za pomocą poleceń.
Instalacja i tożsamość
lg to jednoplikowy skrypt Node bez zależności (Node 18+), opublikowany w npm jako @lgstv/lg. Pakiet instaluje dwa identyczne polecenia, lg i logistivo — użyj logistivo, jeśli lg jest już aliasem na twoim komputerze. Ponieważ to jeden plik, skopiowanie lg.mjs na serwer ERP klienta również działa. Do zbudowania integracji ERP/CRM nie potrzebujesz klienta — te same polecenia są dostępne przez HTTP.
1. Instalacja — Potrzebujesz tylko Node 18 lub nowszego; nie ma innych zależności. Zainstaluj globalnie albo uruchom bez instalacji przez npx.
2. Logowanie kodem zatwierdzenia — lg login wyświetla krótki kod zatwierdzenia i otwiera w przeglądarce adres logistivo.com/connect; przez SSH, w CI lub z --no-browser tylko wypisuje adres, który możesz otworzyć na dowolnym urządzeniu, także na telefonie. Zaloguj się tam jak zwykle, sprawdź, czy kod na stronie jest tym samym kodem co w terminalu, wybierz dostęp tylko do odczytu albo do odczytu i wykonywania działań, a następnie zatwierdź. Do terminala nie wpisuje się niczego tajnego: ani hasła, ani klucza, ani kodu jednorazowego. Sesja pozostaje potem zalogowana na tym komputerze — zamknięcie terminala nie wylogowuje, a lg sam odnawia token dostępu, zanim ten wygaśnie. lg logout kończy sesję również na serwerze; możesz ją też usunąć w panelu w Settings › Integration keys › AI and CLI connections. lg login --password (e-mail i hasło) pozostaje jako rozwiązanie awaryjne. Wymaga lg 0.11 lub nowszego.
3. Dla serwerów i CI: klucz, nie kod zatwierdzenia — Na serwerze ani w zadaniu CI nie ma nikogo, kto zatwierdziłby kod w przeglądarce. Wydaj klucz w panelu (Settings › Integration keys) albo poleceniem lg keys create — opcjonalnie w imieniu dedykowanego członka zespołu o wąskim zakresie uprawnień — i umieść go w LOGISTIVO_TOKEN albo zapisz przez lg login --api-key. Gdy zmienna jest ustawiona, plik konfiguracyjny nigdy nie jest odczytywany. Szczegóły: sekcja „Połączenie za pomocą klucza API”.
4. Sprawdź instalację i przejrzyj katalog — lg commands wyświetla wszystkie polecenia, które widzi twoja rola, pogrupowane według domen; lg help pokazuje czasowniki tej domeny, a lg help — pełną listę parametrów jednego polecenia z typami i informacją, które są wymagane. Żaden z tych tekstów nie mieszka w kliencie — wszystko pochodzi z katalogu. Pamiętaj, że lista zależy od twojej roli: czasowniki jednej domeny nie są takie same dla przewoźnika i dla nadawcy (na przykład loads set-status jest tylko w katalogu przewoźnika). Jeśli brakuje czasownika, sprawdź swoją rolę, zanim sprawdzisz instalację.
Nigdy nie umieszczaj klucza w systemie kontroli wersji, logu CI ani oknie czatu. Jeśli logowanie odbyło się kodem zatwierdzenia lub kluczem integracyjnym, lg logout kończy sesję również na serwerze; w sesji hasłowej (lg login --password) usuwa tylko LOKALNĄ kopię i wyraźnie to komunikuje. Rejestr audytu przechowuje twoje argumenty, ale maskuje jako *** każde pole, którego nazwa zawiera token, password, IBAN, card lub OTP, oraz każdy parametr, który polecenie deklaruje jako tajny.
LOGISTIVO_TOKEN — Osobisty token dostępu. Gdy jest ustawiony, plik konfiguracyjny nigdy nie jest odczytywany — to preferowana droga w CI i na serwerach.
LOGISTIVO_BASE_URL — Adres główny serwera. Domyślnie https://logistivo.com. Zmieniaj go tylko wtedy, gdy wskazujesz własne środowisko; flaga --base-url robi to samo dla pojedynczego polecenia.
LOGISTIVO_HOME — Folder na plik konfiguracyjny i pamięć podręczną katalogu poleceń. Domyślnie ~/.logistivo. Rozdziel go, jeśli pracujesz z dwoma kontami na jednym komputerze.
LOGISTIVO_PROFILE — Profil, w ramach którego uruchamiasz polecenia. `lg profile use` to trwały wybór; ta zmienna służy do pojedynczego uruchomienia i jest najkrótszym sposobem przełączania między profilem produkcyjnym a sandboxowym w CI. Nieznana nazwa profilu nie jest po cichu ignorowana — powoduje błąd.
NO_COLOR — Gdy jest ustawiona, kolory ANSI nie są wypisywane (trwała forma flagi `--no-color`). Włącz ją dla mostu, który pisze do pliku logu lub wyjścia CI; sekwencje sterujące kolorami psują narzędzia, które później czytają te logi.
Ergonomia klienta
Te funkcje ułatwiają codzienną pracę z klientem `lg`. Żadna z nich nie zmienia kontraktu HTTP — pomiń tę sekcję, jeśli integrujesz się bezpośrednio przez HTTP.
Wiele środowisk i kluczy — Trzymaj staging i produkcję albo mosty dla klienta i dla przewoźnika w osobnych profilach. Lista profili nigdy nie wypisuje tokenu; każdy wiersz pokazuje odcisk sha256 tokenu. Katalog poleceń jest buforowany osobno dla każdego profilu, hosta i tokenu, więc dwie role nigdy nie zobaczą nawzajem swoich list poleceń.
Synchronizacja przyrostowa: lg sync — Uruchamia jednym poleceniem pętlę synchronizacji znaną z poradnika: znacznik postępu (watermark) dla każdej encji, updated_since z kursorem, wyjście JSONL i pięciominutowy margines bezpieczeństwa. Do pierwszego pełnego zasilenia danymi użyj --full. Polecenie tylko czyta; nie ma flagi --write. lg sync --list wyznacza na podstawie katalogu encje, które twoja rola może synchronizować.
Obsługa błędów i uzupełnianie w powłoce — Przy 422 klient wskazuje odrzucone pole jako flagę w takiej postaci, w jakiej została wpisana, wraz ze stabilnym error_key i wyjaśnieniem pochodzącym z samego katalogu. Przy 409 wypisuje gotowy wiersz polecenia z --yes; przy 429 odczekuje czas podany w Retry-After. Uzupełnianie w powłoce obejmuje domeny, czasowniki, flagi i wartości enum i działa offline.
Tajne parametry nigdy nie trafiają do wiersza poleceń — Kilka poleceń przyjmuje sekret — na przykład podłączenie integracji księgowej Paraşüt wymaga danych uwierzytelniających klienta i hasła tego systemu. lg nigdy nie przyjmuje takiej wartości jako flagi, bo trafiłaby do historii powłoki i do wyjścia ps: pyta o nią bez echa albo czyta ją z ---file=PATH lub ze standardowego wejścia (---file=-) i trzyma ją wyłącznie w pamięci. Polecenie, którego wymagany parametr jest tajny, działa tylko z lg: wywołane z czatu, przez MCP lub wewnątrz lg batch zostaje odrzucone z SECRET_REQUIRES_CLI. Rejestr audytu zawsze zapisuje tę wartość jako ***.
Połączenie za pomocą klucza API
ERP, CRM, skrypt lub agent AI łączy się z Logistivo kluczem integracyjnym wydanym w panelu albo poleceniem lg keys create. Klucz działa w imieniu prawdziwego członka zespołu: rola tej osoby decyduje o liście poleceń, poziom dostępu klucza — o tym, jak poważna może być praca, a gdy ta osoba odchodzi z zespołu, klucz umiera razem z nią. Nie ma syntetycznego „konta serwisowego” i nie będzie — izolacja multi-tenant jest związana z użytkownikiem, a most bez właściciela to taki, który latami po cichu dalej zapisuje.
1. Wydaj klucz w panelu — Settings › Integration keys › New key. Nadaj mu nazwę („Nocna synchronizacja ERP”), wybierz zakres i poziom dostępu oraz opcjonalnie skróć okres ważności. Klucz jest pokazywany raz, tylko na tym ekranie; serwer go nie przechowuje. Jeśli go zgubisz, Rotate wydaje nowy — stary natychmiast traci ważność.
2. Połącz się z terminala — lg login --api-key weryfikuje klucz, wypisuje tożsamość i zakres oraz pobiera katalog poleceń. lg whoami pyta serwer, jako który użytkownik, w jakiej firmie, roli i zakresie działasz. lg logout unieważnia klucz również na serwerze, tak samo jak kończy tam sesję otwartą kodem zatwierdzenia (tylko lg logout w sesji hasłowej tego nie potrafi).
3. Albo zwykłe HTTP — Klucz to token dostępu przesyłany w nagłówku Authorization: Bearer i działa bezpośrednio z trzema endpointami poleceń. Na serwerze lub w CI umieść go w LOGISTIVO_TOKEN; gdy ta zmienna jest ustawiona, plik konfiguracyjny nigdy nie jest odczytywany.
4. Albo zarządzaj kluczami z terminala: lg keys — lg keys to terminalowy odpowiednik ekranu w panelu: te same endpointy, ta sama bramka (uprawnienie do zarządzania zespołem oraz klucz na poziomie manager, gdy wywołujesz to kluczem). create, rotate i transfer zwracają nowy token jednorazowo: z --save-profile=NAME trafia on od razu do lokalnego profilu i nigdy nie jest wypisywany; w przeciwnym razie lg wypisuje go raz. W trybie --json token jest dołączany tylko wtedy, gdy dodasz --show-secret, a wywołanie --json bez żadnej z tych flag jest odrzucane przed wysłaniem żądania, więc token nie może po cichu trafić do wyjścia skryptu. rotate, transfer i revoke proszą o potwierdzenie (--yes); klucz jest wskazywany dokładną nazwą lub uuid, nigdy przez zgadywanie. Poziom dostępu przechodzi bez zmian na klucz po rotacji lub przeniesieniu.
Zakres jest egzekwowany na całej powierzchni API, nie tylko w katalogu poleceń: klucz tylko do odczytu przepuszcza żądania odczytu (GET/HEAD/OPTIONS), a każde inne, zapisujące żądanie dostaje 403 forbidden. Są dwa celowe wyjątki i obu strzeże dokładniejsza bramka: endpoint wykonywania poleceń (decyzja wynika z własnej flagi read_only polecenia, bo polecenia niezapisujące też wywołuje się przez POST) oraz klucz unieważniający samego siebie (lg logout, dozwolone także dla klucza tylko do odczytu). Zakres, uprawnienia domenowe i poziom dostępu to trzy niezależne osie i wszystkie muszą przepuścić żądanie: klucz read nie może zapisywać nawet na poziomie manager, klucz write na poziomie employee nie może zarządzać zespołem, a uprawnienie domenowe loads:write nie otwiera prac zarządczych. Wydaj klucz w imieniu członka z najmniejszymi uprawnieniami, które pokrywają twoje potrzeby: rola decyduje o tym, które rekordy w ogóle możesz zobaczyć.
read — Katalog poleceń i polecenia niezapisujące (list, search, preview). Polecenie zapisujące zwraca 403 forbidden — przed bramką potwierdzenia; klucz tylko do odczytu nigdy nawet nie zobaczy 409. Właściwy wybór dla nocnej synchronizacji i raportowania.
write — Każde polecenie. Polecenia wymagające potwierdzenia nadal o nie proszą przez 409; confirm: true (--yes w CLI) działa dokładnie tak jak wcześniej. Zakres nigdy nie luzuje bramki potwierdzenia.
employee — Domyślny dla każdego nowego klucza. Codzienne operacje: ładunki, zapytania transportowe, oferty, kursy, flota i dokumenty floty, dokumenty, kontakty — każde polecenie, które nie wymaga uprawnień zarządczych, plus uprawnienia flotowe. Polecenie, które wymaga więcej, odpowiada 422 z error_key INSUFFICIENT_KEY_LEVEL i required_key_level: manager; odpowiadający mu endpoint REST odpowiada 403 z tym samym kluczem błędu. Właściwy poziom dla nocnej synchronizacji ERP, mostu telematycznego lub skryptu operacyjnego.
manager — Wszystko, co może robić osoba, w imieniu której działa klucz, łącznie z zarządzaniem: członkowie zespołu i role, ustawienia firmy, klucze integracyjne, konta bankowe i ich weryfikacja, zapisane karty, relacje między firmami, wypłaty dla afiliantów. Klucz manager nigdy nie dodaje uprawnienia, którego osoba nie ma — bez uprawnienia do zarządzania zespołem nadal nie może zarządzać zespołem. Klucze, które istniały przed wprowadzeniem poziomów dostępu, są kluczami manager, więc zachowują się dokładnie tak jak wcześniej.
Jeden klucz na integrację — Jeśli CRM i ERP współdzielą klucz, odcięcie jednego oznacza odcięcie drugiego. Daj każdemu mostowi własny klucz; lista i tak pokazuje je po nazwach.
Rotacja — Wydaje nowy token i natychmiast unieważnia stary; pozostały okres ważności zostaje zachowany. Używaj jej przy podejrzeniu wycieku i w regularnych odstępach. Integracja dostaje 401, dopóki nie zostanie zaktualizowana nowym tokenem.
Unieważnienie — Klucz zostaje trwale zamknięty; tego nie da się cofnąć, w razie potrzeby wydaj nowy klucz. Jeśli członek, w imieniu którego działa klucz, zostanie usunięty z zespołu lub dezaktywowany, klucz sam przestaje działać.
Okres ważności i limit — Domyślna ważność to 180 dni; przy tworzeniu możesz ją skrócić, nigdy wydłużyć. Użytkownik może mieć najwyżej 10 aktywnych kluczy. Czas ostatniego użycia jest widoczny na liście; przy nigdy nieużytym kluczu jest to wyraźnie zaznaczone.
Kto zarządza — Wydawanie, rotacja, przenoszenie i unieważnianie są dostępne dla menedżerów z uprawnieniem do zarządzania zespołem — ta sama bramka co przy dodawaniu lub usuwaniu członków zespołu — a gdy robi się to kluczem integracyjnym, ten klucz musi być na poziomie manager. Menedżer może wydać klucz w imieniu innego członka; dla mostu zalecany jest dedykowany członek o wąskim zakresie uprawnień.
Pierwsze dziesięć minut: od panelu do pierwszego wywołania
Najdroższe minuty integracji to pierwsze dziesięć. Cztery poniższe kroki układają tę ścieżkę w kolejności; ta sama kolejność istnieje w panelu jako kreator (Settings › Integration › Setup wizard), a kreator wywołuje dokładnie opisane tu endpointy. Deweloper bez dostępu do kreatora dociera w to samo miejsce, czytając tę sekcję.
Żaden z czterech kroków nie kończy się na „wysłane”. Na pytanie, czy klucz naprawdę działa, odpowiada rejestr żądań; na pytanie, czy webhook naprawdę dociera — rejestr dostarczeń. Oba są dostępne w panelu i w lg. Konfiguracja, której nikt nie mierzy, to konfiguracja, o której tylko się wierzy, że działa.
1. Zdecyduj, co będziesz robić — najpierw ustaw zakres — Nie da się później decydować, co klucz może widzieć: zakres wybierasz przy jego wydawaniu. Są dwie osie. Zakres zgrubny (read / write) odpowiada tylko na pytanie „czy może zapisywać”. Zakres szczegółowy (uprawnienia domenowe: loads:read, invoices:write) mówi, których domen klucz może dotykać, a w chwili jego ustawienia klucz staje się fail-closed (domyślnie zamknięty) — każda niewybrana domena i każdy endpoint, który nie mapuje się na żadną domenę, zwraca 403. Lista domen w panelu nie jest pisana ręcznie; wynika z bieżącego katalogu poleceń twojej roli i pokazuje, ile poleceń i endpointów REST otwiera każda domena. Katalog poleceń oraz endpointy „kim jestem” (current) i „wyloguj” są zawsze wyłączone z zakresu: klucz musi zawsze móc opisać i zamknąć sam siebie. Trzecią osią jest poziom dostępu: employee (domyślny) wykonuje codzienne operacje, manager zajmuje się też zespołem, ustawieniami, kluczami i pieniędzmi. Wybierz employee, chyba że most wykonuje prace zarządcze.
2. Wydaj klucz — token jest pokazywany raz — Settings › Integration › New key. Nadaj mu nazwę („Nocna synchronizacja ERP”), wybierz użytkownika, w imieniu którego działa, i poziom dostępu, a jeśli chcesz, skróć okres ważności. Surowy token jest zwracany tylko w tej odpowiedzi; serwer go nie przechowuje, a w panelu nie ma opcji „pokaż ponownie”. Jeśli go zgubisz, wykonaj rotację, aby dostać nowy — stary natychmiast przestaje działać. Nigdy nie umieszczaj tokenu w systemie kontroli wersji, logu CI ani oknie czatu; umieść go w magazynie sekretów systemu docelowego.
3. Wykonaj pierwsze wywołanie — i sprawdź, czy NAPRAWDĘ dotarło — Wystarczą dwa żądania. Pierwsze potwierdza twoją tożsamość (jest wyłączone z zakresu i działa z każdym kluczem): czy zakres jest taki, jakiego oczekujesz, czy status to active, czy zbliża się expires_at. Drugie odczytuje prawdziwe dane z wybranej domeny. Jeśli przejdzie, tożsamość, zakres, bramka weryfikacji e-mail i ścieżka sieciowa są poprawne. Jeśli nie — nie zgaduj: własny rejestr żądań klucza pokazuje wiersz po wierszu, który endpoint został odrzucony, z jakim kodem i z jakim stabilnym kluczem błędu (INSUFFICIENT_SCOPE, IP_NOT_ALLOWED, KEY_ACTOR_BLOCKED …). W panelu ten rejestr to okno „Recent requests”; w terminalu — lg logs. Kreator obserwuje właśnie ten rejestr i nie oznaczy kroku na zielono, dopóki nie zobaczy prawdziwego udanego wywołania.
4. Skonfiguruj webhook — i zanim cokolwiek zrobisz, zweryfikuj podpis — Czekanie na zdarzenia jest tańsze niż pytanie co minutę. Zarejestruj adres https, wybierz zdarzenia, które cię interesują, i powiąż subskrypcję ze swoim kluczem: jeśli klucz zostanie unieważniony, dostarczanie też się zatrzyma. Sekret jest pokazywany tylko raz, przy tworzeniu. Twój endpoint odbierający musi najpierw zweryfikować podpis: podpisywany ciąg to "{t}.{raw body}", a algorytm to HMAC-SHA256; znacznik czasu jest WEWNĄTRZ podpisu, więc odrzucaj każde żądanie starsze niż 300 sekund, nawet gdy podpis jest prawidłowy. Porównuj w stałym czasie i nigdy nie serializuj treści ponownie — w chwili, gdy sparsujesz JSON i wypiszesz go z powrotem, podpis przestaje się zgadzać. W panelu „Send test” wysyła prawdziwy podpisany ping, a ty możesz śledzić dostarczenie próba po próbie.
Sandbox: ćwicz zapisy bez dotykania produkcji
Przebieg próbny (dry_run) mówi ci, co polecenie BY zrobiło; ale to, czy idempotencja naprawdę odtwarza wynik, czy webhook naprawdę zostaje dostarczony, jak wyglądają gałęzie błędów i skąd pochodzą kredyty, widać dopiero przy PRAWDZIWYM zapisie. Do tego służy sandbox (środowisko testowe): osobny tenant odzwierciedlający twoją firmę — ten sam kod, ten sam katalog poleceń — który nigdy nie dotyka twojego produkcyjnego rejestru.
Sandbox to nie flaga żądania, tylko TENANT. Osobna firma Logistivo otwarta dla twojej: własny użytkownik, własny pakiet, własny rejestr kredytów, własne subskrypcje webhooków. Środowisko jest WYPROWADZANE z firmy, do której należy klucz, i wywołujący nie może go podać, więc nawet jeśli wybierzesz zły profil, żądanie zatrzymuje się po stronie serwera z 403 ENVIRONMENT_MISMATCH. Sytuacja „miało pójść do sandboxa, a poszło na produkcję” jest strukturalnie niemożliwa.
Powierzchnia jest identyczna — zmierzono to: katalog, który pobiera klucz sandboxowy, jest tym samym katalogiem, który pobiera twój klucz produkcyjny (dla klucza nadawcy po obu stronach to katalog z 646 poleceń). Most, który działa w sandboxie, działa na produkcji; niczego, czego się nauczysz, nie trzeba uczyć się dwa razy.
Sandbox nie otwiera się pusty: zawiera wygenerowane (NIE skopiowane) dane startowe — kontakty, ładunki w obu kierunkach i zapytania transportowe. Nazwy są jawnie zmyślone, a adresy e-mail należą do domeny @sandbox.invalid; żaden wiersz prawdziwego tenanta nigdy nie jest odczytywany, klonowany ani używany jako szablon.
Celowo NIE ma przycisku resetu i żaden rekord, plik ani dokument nigdy nie jest usuwany. Jeśli chcesz zacząć od czysta, odnowienie otwiera nową generację, a stara pozostaje — wycofana. Kilkaset nagromadzonych wierszy próbnych nic nie kosztuje w porównaniu z procedurą usuwania podpiętą do niewłaściwego tenanta.
1. Otwórz sandbox — Jeden sandbox na firmę. Endpoint wymaga uprawnienia do zarządzania zespołem (team.manage), więc robi to administrator w twojej firmie. Jeśli sandbox już istnieje, ten sam endpoint odpowiada przez GET jego stanem: identyfikator firmy, pozostałe kredyty, liczba aktywnych kluczy, subskrypcje, historia generacji i limity.
2. Wydaj klucz sandboxowy i zachowaj go jako drugi profil — Klucz jest wydawany w imieniu własnego użytkownika mostu w sandboxie i wraca oznaczony environment: sandbox; surowy token pojawia się tylko w tej jednej odpowiedzi. Po stronie lg nie zastępuj swojego klucza produkcyjnego — zachowaj OBA jako osobne profile; --sandbox i --live to selektory dla pojedynczego uruchomienia.
3. Naprawdę zapisuj — Tutaj bez --dry-run; zapis jest całym sensem. Wyślij ten sam klucz idempotencji dwa razy i zobacz, jak druga odpowiedź wraca jako status: replayed — to zmierzony wynik w sandboxie. Celowo wywołaj polecenie z bramką bez potwierdzenia i przeczytaj treść 409; spróbuj polecenia spoza swojego zakresu i przeczytaj odmowę. Nic z tego nie zostawia śladu w twoim produkcyjnym rejestrze: twoje produkcyjne saldo pozostaje takie samo przez cały ten przebieg.
4. Przed uruchomieniem produkcyjnym przeczytaj listę kontrolną — Endpoint go-live odpowiada na podstawie tego, co FAKTYCZNIE wydarzyło się w sandboxie: czy były zapisy, czy pojawiły się gałęzie błędów, czy webhook został dostarczony, czy odbiornik został przeniesiony z adresu próbnego, czy klucz ma ustawioną datę wygaśnięcia. Każda pozycja wraca jako pass / todo / unknown. Ta sama odpowiedź zawiera też PROPOZYCJĘ ZAKRESU wyprowadzoną z poleceń faktycznie wywołanych — użyj jej, aby wydać klucz produkcyjny nie szerszy, niż potrzebujesz.
Kredyty i fakturowanie — Sandbox ma własny rejestr kredytów, a twoje produkcyjne saldo się nie zmienia. To kwestia struktury, a nie kontroli: kredyty są liczone per firma, a sandbox to osobna firma. Otwiera się w darmowym planie, nie ma metody płatności i jest poza oknem miesięcznych obciążeń — żadną drogą nie może dojść do faktury.
Marketplace — Zapytanie transportowe otwarte w sandboxie NIE pojawia się na ekranach prawdziwych przewoźników i NIE trafia do ich skrzynek e-mail ani powiadomień push; ty też nie widzisz prawdziwych zapytań transportowych. Podział jest symetryczny i egzekwowany w dwóch osobnych kwerendach: komu zapytanie jest WIDOCZNE i do kogo jest WYSYŁANE, to różne pytania.
Webhooki — Subskrypcje też noszą znacznik środowiska. Zdarzenie z sandboxa nigdy nie jest dostarczane do subskrypcji produkcyjnej, a zdarzenie produkcyjne nigdy nie trafia do sandboxowej; dla subskrypcji, której znacznik się rozjechał, nie jest otwierane żadne dostarczenie. Ponieważ limit subskrypcji jest liczony per firma, twoje subskrypcje próbne nie uszczuplają limitu produkcyjnego.
Dane startowe — Przykładowe rekordy w sandboxie są GENEROWANE, nigdy kopiowane od prawdziwych tenantów. Zasilanie jest idempotentne: drugie wywołanie nie kładzie drugiej warstwy danych startowych na twoje własne rekordy.
Ten sam katalog — Twoja rola jest twoją rolą także w sandboxie, a lista poleceń jest identyczna — zmierzono: katalog z 646 poleceń po obu stronach. Sandbox to nie okrojone demo; to bliźniak twojej firmy.
Dzisiejsze ograniczenie: subskrypcjami webhooków nie da się zarządzać kluczem sandboxowym — Endpointy subskrypcji wymagają uprawnienia do zarządzania zespołem (team.manage), a użytkownik mostu w sandboxie nie ma roli zespołowej, więc `lg --sandbox webhooks …` dziś odpowiada 403. Cała powierzchnia poleceń działa — ograniczenie dotyczy tylko rejestru subskrypcji. Jeśli chcesz przećwiczyć webhooki w sandboxie, zwróć się do wsparcia; jest to zmierzone i odnotowane jako otwarta luka.
GET /api/common/integration-sandbox — Stan: czy istnieje, która firma, pozostałe kredyty, liczba aktywnych kluczy i subskrypcji, historia generacji, limity oraz przewodnik po wyzwalaczach pokazujący, które polecenie wywołuje które zdarzenie.
POST /api/common/integration-sandbox — Otwiera sandbox (jeden na firmę, idempotentnie). Wymaga uprawnienia team.manage.
POST /api/common/integration-sandbox/keys — 201 + klucz i surowy token (tylko tutaj, tylko raz). Znacznik environment: sandbox jest wyprowadzany z firmy; wywołujący nie może go podać.
GET /api/common/integration-sandbox/go-live — Lista kontrolna go-live i propozycja zakresu — obliczone na podstawie twojego rzeczywistego ruchu w sandboxie.
POST /api/common/integration-sandbox/renew — Otwiera nową GENERACJĘ sandboxa i wycofuje poprzednią.
Model poleceń
Jest jedna gramatyka i nie ma od niej wyjątków. Aby wiedzieć, jak wywołać polecenie, potrzebujesz tylko tego, co mówi o nim katalog.
lg loads list --status=in_transport --limit=20 --json
Nazwy flag to nazwy parametrów ze schematu, a lg akceptuje obie pisownie: --load_code i --load-code trafiają do tego samego pola (lg help wypisuje formę kebab-case). Widząc flagę, wiesz więc, do którego pola JSON trafi, a przejście z CLI na HTTP nie wymaga tłumaczenia nazw. Parametr logiczny zapisany bez wartości oznacza true (--only_open); przeciwieństwem jest --no-only_open. Argument, którego wartość zaczyna się od myślnika, zapisuj jako --flag=value, inaczej zapomniana flaga po cichu połknie następną jako swoją wartość. W poleceniu przyjmującym plik poprzedź ścieżkę lokalną znakiem @ (--attachment_uuid=@./cmr.pdf) — zob. Polecenia przyjmujące pliki.
lg — Klient.
loads — Domena — encja, na której pracujesz, w liczbie mnogiej.
list — Czasownik — to, co robisz z tą encją, pochodzący z zamkniętego słownika, który rośnie tylko w wyniku świadomej decyzji: czasowniki proste (list, get, create, update, delete, search, preview, generate, extract …) oraz złożone, które nazywają to, co jest dołączane lub zmieniane (add-document, set-status, assign-driver). lg help wyświetla czasowniki domeny.
--status=in_transport — Parametr — jego nazwa to dokładnie nazwa parametru w JSON Schema, a wartość musi pasować do typu ze schematu. Nieprawidłowa wartość pola enum nigdy nie dociera do serwera.
--limit=20 — Liczba wierszy w poleceniach listujących. Limit jest podany w opisie parametru każdego polecenia — zwykle 20 przy zwykłym wywołaniu listującym i do 100 w trybie synchronizacji (z cursor lub updated_since).
--json — Surowe wyjście JSON.
--json — Wypisuje surowy JSON. To jedyny poprawny format dla skryptów: domyślna wyrównana tabela jest dla ludzi, dobiera kolumny na podstawie danych i może zmienić układ bez uprzedzenia. Nigdy nie pisz skryptu, który parsuje wyjście tabelaryczne.
--yes, -y — Przechodzi przez bramkę potwierdzenia (confirm: true przez HTTP). Używaj jej tylko w skrypcie, który wie, co za chwilę zrobi; w poleceniu nieodwracalnym ta flaga jest skrótem od „nie ma cofania”.
--idempotency-key= — Sprawia, że ponawianie polecenia zapisującego jest bezpieczne. Drugie wywołanie z tym samym kluczem nie uruchamia polecenia ponownie; zwraca pierwszy wynik. Jeśli budujesz pętlę ponowień, wygeneruj klucz SAMODZIELNIE i wysyłaj ten sam przy każdej próbie.
--dry-run — Zamiast polecenia uruchamia przebieg próbny: walidacja, bramki i wyliczenie kredytów są wykonywane, nic nie zostaje zapisane (zob. sekcję o przebiegu próbnym). Działa w każdym poleceniu i w lg batch.
--refresh — Wymusza odświeżenie katalogu. lg przechowuje katalog w pamięci podręcznej przez godzinę; jeśli wiesz, że polecenie zostało właśnie dodane na serwerze, użyj tej flagi zamiast czekać.
--help, -h — Wypisuje opis polecenia z katalogu, każdy parametr, jego typ, wartości enum i informację, czy jest wymagany. W kliencie nie ma żadnego pliku pomocy.
--profile=, --sandbox, --live — Profil, w ramach którego wykonać to jedno wywołanie. --sandbox i --live wybierają profil z kluczem sandboxowym lub produkcyjnym; środowisko jest ustalane na serwerze na podstawie klucza, więc niezgodność kończy się błędem 403 ENVIRONMENT_MISMATCH zamiast zapisu w niewłaściwym miejscu.
--base-url, --timeout, --verbose, --no-color, --version — Kolejno: skierowanie jednego polecenia na inny serwer, limit czasu w sekundach, szczegóły żądania/odpowiedzi, wyłączenie kolorów ANSI oraz wersja klienta.
Prawdziwe przykłady
Każde poniższe polecenie istnieje dziś w katalogu; żadna nazwa ani parametr nie są tu wymyślone. Wyniki są skrócone. Pokazują poziom `data.result`; przez HTTP ten sam obiekt przychodzi wewnątrz koperty (envelope) `{success, data:{…}}` (zob. API poleceń przez HTTP).
Ładunki, które są teraz w drodze — lg loads list --status=in_transport --limit=20
Jeden ładunek w całości, surowy JSON — lg loads get --load_code=FSK2158 --json
Otwarte flagi spójności dokumentów — lg loads list-problems --only_open=true --limit=10
Ustal kraj — lg countries search --query=Germany --json
Filtruj ustalonym identyfikatorem — lg loads list --receiving_country_id=57 --date_from=2026-09-01 --limit=20
Znajdź kod HS na podstawie nazwy produktu — lg tariffs search --query="aluminium profile"
Przesuń ładunek do następnego etapu (tylko rola przewoźnika) — lg loads set-status --load_code=FSK2158 --status=transit --date=2026-08-21 --yes
Szkic — lg export-documents create --doc_type=proforma-invoice --currency_code=EUR --json
Wygeneruj (z bramką) — lg export-documents generate --document_id=8412 --yes
Bez klienta: API poleceń przez HTTP
lg to wygoda, a nie jedyne drzwi. Katalog i wykonanie przechodzą przez trzy endpointy HTTP (pliki mają czwarty, endpoint przesyłania — zob. Polecenia przyjmujące pliki); integracja ERP lub CRM łączy się tutaj bezpośrednio. Tożsamością jest osobisty token dostępu przesyłany w Authorization: Bearer. KAŻDA odpowiedź przychodzi w tej samej kopercie: `{ "success": bool, "data": { … }, "code": "…", "message": { … } }`. Cały kontrakt mieszka wewnątrz `data` — `contract_version`, `command`, `status` oraz, jako wynik polecenia, `result`; w razie niepowodzenia `error_code`, `error_key` i `error`. Przykłady odpowiedzi na tej stronie, dla oszczędności miejsca, pokazują obiekt `data`, a nie kopertę; nie zapomnij rozpakować `data` we własnym kodzie. `lg --json` również wypisuje CAŁĄ kopertę, dlatego ścieżki jq zaczynają się od `.data.result…`. Jedynym wyjątkiem jest `/api/public/status`: ten endpoint nie ma koperty, aby watchdogi mogły alarmować bez jej parsowania.
Proszenie o potwierdzenie przez 200 + ok:false jest zabronione i nigdy się nie zdarzy. Powód jest prosty: klienci traktują 200 jako sukces, więc prośba o potwierdzenie zwrócona jako 200 po cichu przerwałaby przepływ i nikt by tego nie zauważył. Potwierdzenie to zawsze 409.
GET /api/common/commands — Cały katalog, który widzi twoja rola: contract_version; dla każdego polecenia name, domain, verb, description, JSON Schema, read_only, confirmation_needed, irreversible, credit_cost, since, deprecated_at, replaced_by, aliases oraz pola dostępu key_level, permission, file_params, secret_parameters i cli_only; na najwyższym poziomie słownik error_keys, rate_limits, idempotency_ttl_hours, role twojego katalogu, kontrakt attachments (przesyłanie) oraz poziom dostępu klucza, którym wywołujesz. Wysyła ETag; If-None-Match odpowiada 304. ?domain= dopasowuje także starą domenę (alias). Buduj klienta na tej podstawie; nie koduj listy poleceń na sztywno.
GET /api/common/commands/{name} — Jedno polecenie w całości. name to zamrożona nazwa polecenia z katalogu (list_loads), a nie tożsamość CLI. Wycofywane polecenie odpowiada z nagłówkiem X-Deprecated.
POST /api/common/commands/{name} — Wykonanie. Treść: { args, confirm?, idempotency_key? }. Status HTTP odpowiedzi jest samym wynikiem — wszystko inne niż 200 to informacja, a nie szum. Błędy niosą error_code (transport) oraz, przy odrzuceniach biznesowych, error_key.
Polecenia przyjmujące pliki
Do 38 poleceń w tabeli przekazujesz dokument lub zdjęcie: dołączenie CMR do ładunku, odczytanie kodów HS z faktury, utworzenie pojazdu z dowodu rejestracyjnego, oszacowanie palety ze zdjęć, przesłanie dokumentu firmy, porównanie faktury z listą pakowania (packing list). W przeglądarce upuszczasz plik do formularza; wszędzie indziej trwa to dwa kroki — prześlij plik, a potem przekaż jego identyfikator poleceniu.
Parametr przyjmuje plik, gdy jego nazwa kończy się na attachment_uuid lub attachment_uuids — photos[].attachment_uuid wewnątrz listy, front_attachment_uuid na czeku. Nie musisz tego pamiętać: każdy wiersz katalogu zawiera file_params z dokładnymi ścieżkami, schemat oznacza te pola (format: uuid, x-logistivo-file: true), a odpowiedź katalogu zawiera blok attachments z adresem przesyłania, akceptowanymi typami, limitami rozmiaru i czasem życia. lg help również je pokazuje.
Przesyłanie to zapis, więc klucz z zakresem odczytu nie może przesyłać plików; może to zrobić każdy klucz z zakresem zapisu, na dowolnym poziomie dostępu. Przesłane pliki należą do użytkownika, a nie do klucza: dwa klucze tego samego użytkownika widzą te same pliki i nikt nie może użyć cudzych. Identyfikator nieznany, wygasły lub nienależący do ciebie po prostu nie zostaje znaleziony, a powód nie jest ujawniany.
Załączniki czatu w panelu i pliki przesłane dla poleceń to oddzielne przestrzenie: pliku dołączonego w czacie asystenta nie można przekazać poleceniu po identyfikatorze, a plik przesłany dla polecenia nigdy nie pojawia się w wątku czatu.
Przesłanie nie jest poleceniem i samo w sobie nie ma skutku biznesowego: z twoimi danymi nic się nie dzieje, dopóki polecenie nie użyje identyfikatora. Dlatego też przesyłanie nigdy nie prosi o potwierdzenie — bramkę niesie polecenie, które zużywa plik.
1. lg: poprzedź ścieżkę lokalną znakiem @ — lg najpierw przesyła plik, a potem uruchamia polecenie ze zwróconym identyfikatorem; wartość bez @ to identyfikator pliku przesłanego wcześniej. Listy przyjmują ścieżki rozdzielone przecinkami lub powtórzoną flagę, pola zagnieżdżone przyjmują JSON, a --file to skrót, gdy polecenie ma dokładnie jedno pole plikowe najwyższego poziomu. lg sprawdza każdy plik lokalnie (istnienie, rozmiar, typ), zanim cokolwiek zostanie wysłane, a lg batch przesyła każdy odrębny plik raz, zanim wsad zostanie uruchomiony.
2. HTTP: prześlij, potem przekaż attachment_uuid — Wyślij plik jako multipart/form-data w polu o nazwie file. Nowe przesłanie odpowiada 201; ten sam plik przesłany ponownie przez tego samego użytkownika odpowiada 200 ze statusem replayed i tym samym identyfikatorem, a nic nie zostaje zapisane. Jak wszędzie na tej stronie, przykład pokazuje obiekt data wewnątrz koperty.
3. MCP: narzędzie upload_attachment — Klient MCP nie może wysłać multipart, więc kanał oferuje jedno dodatkowe narzędzie, którego nie ma w katalogu: upload_attachment przyjmuje nazwę pliku i zawartość w base64 i zwraca ten sam attachment_uuid. Wywołuje tę samą usługę co przesyłanie przez HTTP, według tych samych zasad.
Typ wynika z zawartości — Nazwa pliku i zadeklarowany typ są ignorowane; zapisywane rozszerzenie to rozszerzenie wykryte. Akceptowane do przesłania: jpg, jpeg, png, webp, heic, heif, pdf, xlsx, xls, csv, txt, doc, docx, xml, zip. Każde polecenie stosuje następnie własną, węższą listę, zanim cokolwiek się wykona, i odpowiada UNSUPPORTED_FILE_TYPE z akceptowanymi typami albo FILE_TOO_LARGE.
Rozmiar — Obrazy do 10 MB, inne pliki do 15 MB.
Czas życia — Przesłanego pliku można używać przez 24 h. Potem nie jest już rozwiązywany (ATTACHMENT_NOT_FOUND) — nie jest usuwany. Jeśli polecenie zawiedzie z tego powodu, prześlij plik ponownie.
Ten sam plik, ten sam identyfikator — Ponowne przesłanie tego samego pliku (ta sama nazwa, rozmiar i zawartość) zwraca istniejący identyfikator zamiast zapisywać nowy, o ile pozostała mu co najmniej godzina ważności, i nie zużywa twojego dziennego limitu.
Dzienne limity — Limit przesłań na użytkownika: 300 dziennie (TOO_MANY_FILES), limit na firmę: 2 GB dziennie (DAILY_LIMIT_REACHED); oba odpowiadają 429 z retry_after.
POST /api/common/commands:upload — Przesyłanie multipart w polu file. 201 dla nowego przesłania, 200 ze statusem replayed dla tego samego pliku. Zwraca data.attachment: attachment_uuid, filename, mime_type, size_bytes, sha256, extraction_status, expires_at i reused.
Bramka potwierdzenia i polecenia nieodwracalne
Każde polecenie w katalogu ma dwie flagi: confirmation_needed (czy przed uruchomieniem wymaga wyraźnej zgody) i irreversible (czy jego efekt można cofnąć). To osobne pytania i oba są egzekwowane na serwerze, a nie zostawione dobrym manierom klienta.
Bramka dotyczy odpowiedzialności, a nie reguł biznesowych. Złożenie oferty to pierwszy krok do umowy przewozowej; wystawienie faktury tworzy zapis księgowy; ruch magazynowy zmienia księgę. Żadnej z tych rzeczy nie powinno się dać uruchomić dwa razy przez przypadek.
Bramka jest odczytywana z polecenia FAKTYCZNIE wykonywanego. Gdy jedno polecenie opakowuje inne — jak robi to ogólny wykonawca w czacie — bramka pochodzi z flag polecenia, które naprawdę się wykona, a nie z opakowania. Przy stałej fladze jedna z dwóch awarii byłaby nieunikniona: albo polecenie faktury wykonałoby się bez potwierdzenia, albo każde wyszukanie kraju wywoływałoby kartę potwierdzenia.
read_only i brak bramki to nie to samo. Istnieją trzy różne stany: invoices preview nie ma bramki i niczego nie zapisuje; loads create ma bramkę i zapisuje; invoices create nie ma bramki, ale zapisuje — powstaje szkic. Rozstrzyga jeden test: czy po powrocie polecenia zmienił się jakiś wiersz w bazie danych?
Niektóre działania nie stoją za tą bramką, bo w ogóle nie są poleceniami: zakup pakietu, dodanie karty z 3D Secure, akceptacja tekstów prawnych i zamknięcie konta odbywają się we własnej przeglądarce danej osoby. Dla nich lg handoff-links generate zwraca link do logistivo.com — bezpłatnie, niczego nie zapisując, bez żadnego sekretu — a osoba kończy krok tam. Żadna flaga, niezależnie od ustawienia, nie zamienia płatności ani zgody w wywołanie API.
Technicznie integracja może automatycznie przechodzić przez bramkę przy każdym wywołaniu, ale nie jest to zalecane. Właściwy wzorzec to automatyzowanie bramki tylko dla poleceń, o których wiesz, że są odwracalne, i kierowanie nieodwracalnych do kolejki człowieka.
1. Wywołaj — Wywołaj polecenie objęte bramką bez confirm. Nic się nie zmienia.
2. Przeczytaj podsumowanie — Dostajesz 409; confirmation.summary w treści to zdanie napisane dla człowieka („Zostanie wystawiona faktura: X Ltd, 1 200,00 TRY”), a nie zrzut surowych argumentów. Polecenia pieniężne zawierają też ustrukturyzowany podgląd: pozycje, sumy, ostrzeżenia.
3. Potwierdź — Powtórz to samo wywołanie z confirm: true (--yes w CLI). Polecenia nieodwracalne są oznaczone tak, by wykonały się najwyżej raz.
Przebieg próbny: zobacz, co zrobiłoby polecenie zapisu, bez jego uruchamiania
Najdroższy krok przy podłączaniu mostu ERP to sprawdzanie poprawności treści żądania przez FAKTYCZNE uruchomienie polecenia: szkic faktury w produkcyjnej księdze, spalony kredyt, ręczne sprzątanie. dry_run z tym kończy — dodajesz jedno pole do żądania, polecenie się nie wykonuje, a ty czytasz, co by się stało.
Rejestr składa się dziś z 721 poleceń; spośród nich 327 to polecenia wyłącznie do odczytu, które niczego nie zapisują. Spośród pozostałych 394 poleceń zapisu 346 to polecenia objęte bramką: wywołane bez confirm już odpowiadają 409 i opisują, co by zrobiły. Luka dotyczyła pozostałych 48: szkiców faktur, szkiców dokumentów eksportowych, pozycji — dokładnie tego łańcucha, który most podłącza jako pierwszy. W ich przypadku wywołanie oznaczało wykonanie.
Nawet w poleceniach z bramką była druga luka: walidacja schematu odbywa się PO bramce. Wywołanie z brakującym argumentem dostawało więc najpierw kartę potwierdzenia, było potwierdzane i dopiero wtedy słyszało „brakuje tego pola”. Przebieg próbny odpowiada na oba pytania w jednej wymianie.
A najczęstszy — i najpóźniej wykrywany — błąd mostu jest taki: wysyłasz pole, którego nie ma w schemacie (customer_id tam, gdzie oczekiwane jest recipient_contact_id), serwer po cichu je pomija, polecenie zwraca 200, a rekord ląduje w złym miejscu. Odpowiedź przebiegu próbnego wymienia takie pola z nazwy pod arguments.ignored; żaden komunikat błędu tego nie zrobi.
Przebieg próbny niczego nie zapisuje — i wynika to ze struktury, zanim jeszcze z pomiaru: ścieżka przebiegu próbnego nigdy nie wchodzi do handlera polecenia, więc dotyczy to każdego polecenia, także dodanych później. Zostało to też zmierzone przy wdrożeniu: przechwycono każdą instrukcję SQL wykonaną podczas przebiegów próbnych wszystkich ówczesnych poleceń zapisu w katalogu (dwa zestawy argumentów, dwie role, 178 przebiegów próbnych). Ani jednego INSERT/UPDATE/DELETE, ani jednego zadania w kolejce, ani jednego e-maila; liczby wierszy w 31 tabelach i saldo kredytów pozostały bez zmian.
Kod wyjścia jest taki sam, jaki dałoby prawdziwe wywołanie — wykonałoby się: 0, bramka potwierdzenia: 4, konflikt idempotencji: 2, wszystko inne: 1 — więc „lg … --dry-run || exit” jest sensowną bramką w kroku CI.
1. Wywołaj z dry_run — Dodaj "dry_run": true do treści żądania. Walidacja, bramka ról i zakresu, rozpoznanie celu i wyliczenie kredytów są wykonywane; polecenie — nie.
2. Odczytaj would_execute — To jedyna flaga, na której warto opierać rozgałęzienia. Gdy ma wartość false, would_stop.at wskazuje, gdzie zatrzymałoby się prawdziwe wywołanie: idempotency, target_precheck, confirmation_gate lub arguments.
3. Popraw treść żądania — arguments.ignored wymienia pola, które zostałyby po cichu pominięte, missing_required — wymagane pola, których brakuje, a would_charge — ile kredytów by zeszło i czy saldo je pokrywa.
4. Usuń dry_run — Powtarzaj, aż would_execute będzie true, potem usuń flagę i wykonaj prawdziwe wywołanie. Klucz idempotencji wysłany podczas przebiegu próbnego nie został skonsumowany, więc prawdziwe wywołanie wykona się normalnie.
HTTP to zawsze 200 — „Polecenie by się nie powiodło” nigdy nie przychodzi jako 4xx — sam przebieg próbny się powiódł, a prognoza jest w treści. Wyjątkiem jest odmowa na poziomie transportu i tam zachowuje się dokładnie jak prawdziwe wywołanie: 404 nieznane polecenie, 403 rola/zakres, 429 limit żądań.
Klucz z zakresem odczytu nie wykona przebiegu próbnego polecenia zapisu — Dostaje 403. Przebieg próbny odpowiada na pytanie „co się stanie, jeśli wywołam to TYM KLUCZEM, teraz”; danie kluczowi do odczytu zielonego światła, a potem 403 przy prawdziwym wywołaniu, byłoby dokładnie tą niespodzianką, której przebieg próbny ma zapobiegać.
Klucz idempotencji nie zostaje skonsumowany — Klucz wysłany podczas przebiegu próbnego nie otwiera wiersza w rejestrze, a wygasła blokada nie zostaje zwolniona. Wysyłaj więc klucz, którego zamierzasz użyć naprawdę: przebieg próbny powie ci, czy jest wciąż wolny, czy odtworzyłby wcześniejsze wykonanie, czy koliduje z innym poleceniem.
Łączy się z confirm — Wyślij dry_run i confirm razem, a pytanie brzmi: „co się stanie, jeśli potwierdzę?”. Nadal nic się nie wykonuje.
Przebieg próbny wsadu dotyczy całego wsadu — commands:batch również przyjmuje dry_run, ale flaga należy do wsadu, a nie do elementu (wysłanie jej przy elemencie to 422). Dostajesz raport dla każdego elementu oraz łączny koszt kredytowy wsadu; niewystarczające saldo jest raportowane, a nie odrzucane.
Nie jest darmowy — Każdy przebieg próbny wykonuje prawdziwe zapytania do bazy (podgląd, saldo) i wlicza się do limitu żądań. Nie wykonuj przebiegu próbnego całego katalogu przy każdym wdrożeniu; sprawdzaj w ten sposób tylko zmienione polecenia.
Idempotencja: dlaczego ponawianie nie tworzy duplikatów
ERP nie czyta twojego komunikatu o błędzie, nie widzi twojego ekranu i po przekroczeniu limitu czasu wyśle to samo żądanie ponownie. Ta sekcja istnieje właśnie z powodu tego zachowania.
Wywołanie z idempotency_key wykonuje się najwyżej raz. Drugie wywołanie nie wykonuje polecenia ponownie; zwraca zapisany wynik ze statusem replayed. Gdy zerwie się sieć, gdy żądanie przekroczy limit czasu albo gdy kolejka podejmie to samo zadanie dwa razy, dostajesz pierwszy wynik zamiast zduplikowanej faktury.
Używaj klucza w każdym poleceniu zapisującym. Pole read_only w katalogu daje ci to rozróżnienie za darmo: każde polecenie z read_only: false zasługuje na klucz idempotencji.
Twoja strategia ponowień powinna stosować wykładnicze wydłużanie odstępów (exponential backoff) i wysyłać TEN SAM klucz przy każdej próbie. Generowanie nowego klucza dla każdej próby to to samo, co nieużywanie idempotencji. Nie wysyłaj tego samego klucza równolegle: gwarancja „najwyżej raz” obowiązuje dla kolejnych ponowień, a nie dla dwóch żądań ścigających się ze sobą.
Pułapka 1 — niepowodzenie też zostaje zablokowane — Jeśli pierwsze wykonanie zostało odrzucone przez regułę biznesową (failed), drugie wywołanie z tym samym kluczem zwraca ten sam błąd i ten sam error_key i nie ponawia próby. Poprawienie argumentu i ponowna próba wymagają NOWEGO klucza. Klucz reprezentuje próbę, a nie zamiar.
Pułapka 2 — duży wynik jest odtwarzany bez treści — Rejestr przechowuje wynik tylko wtedy, gdy ma on mniej niż 64 KB. Większy wynik jest odtwarzany ze statusem replayed, ale z pustą treścią. Twoja integracja powinna polegać na sygnale „replayed”, a nie na treści, i pobierać dane odpowiednim poleceniem get.
Pułapka 3 — klucz należy do jednego polecenia — Wysłanie tego samego klucza z innym poleceniem zwraca 409 idempotency_conflict z conflicting_command; nic się nie wykonuje i nic nie jest odtwarzane. Klient, który współdzieli jeden klucz między dwoma czasownikami, jest wadliwy i dowiaduje się o tym z błędu, a nie z cichego odtworzenia.
Pułapka 4 — blokada trwa 24 godziny, a nie wiecznie — Po 24 godzinach ten sam klucz oznacza nowe wykonanie. Ponowienia sieciowe przychodzą w ciągu minut; coroczne, powtarzające się numery dokumentów w ERP nie mogą na zawsze pozostać „replayed”. Katalog publikuje to okno jako idempotency_ttl_hours.
Pułapka 5 — błąd serwera nie blokuje klucza — 5xx server_error to nie odrzucenie biznesowe: klucz nie zostaje związany, więc ponowienie z tym samym kluczem naprawdę uruchamia polecenie. Blokuje tylko failed (pułapka 1).
Zakres i format — twoja firma, dowolny ciąg znaków, najlepiej UUID — Unikalność jest egzekwowana dla pary (twoja firma, klucz): INV-1001 innego tenanta nigdy nie koliduje z twoim i nigdy nie odtworzy twojego wyniku. Użyj zwykłego UUID albo złożenia unikalnego z samej konstrukcji, np. {ERP-document-no}:{verb}.
Synchronizacja przyrostowa i paginacja
Most ERP/CRM powinien pobierać to, co się zmieniło, a nie wszystko co godzinę. Każde polecenie listujące — loads list, demands list-own, contacts list, invoices list, teammates list, load-groups list, reservations list, drivers list, tenders list, products search, warehouses search — przyjmuje dwa wspólne parametry i zwraca jedno wspólne pole.
Dlaczego nie ma offsetu: na żywej tabeli offset się przesuwa. Wiersz wstawiony między dwiema stronami sprawia, że po cichu pomijasz rekord albo liczysz go dwa razy. Kursor przesuwa się tylko do przodu, więc rekord wstawiony lub zaktualizowany w trakcie przechodzenia ląduje na końcu listy: nic nie ginie, nic się nie dubluje.
Pełne zasilenie początkowe to ten sam mechanizm: zacznij od updated_since=1970-01-01T00:00:00Z i podążaj za next_cursor, aż będzie null. Nie ma osobnego endpointu „eksportu”, bo nie jest potrzebny.
To samo z lg: lg loads list --updated_since=2026-09-01T00:00:00Z --limit=100 --json, a potem lg loads list --cursor= --json.
Przy następnej synchronizacji ustaw updated_since na największą zaobserwowaną wartość updated_at. Znaczniki czasu mają precyzję jednej sekundy, więc rekord na granicy może przyjść dwa razy — to nieszkodliwe, o ile po swojej stronie wykonujesz upsert według external_ref lub code. Bez updated_since ani cursor polecenie działa w trybie czatu: kolejność czytelna dla ludzi, najwyżej 20 wierszy, next_cursor równe null i truncated sygnalizujące, że „jest więcej”. Nie używaj tego trybu do synchronizacji.
Maszynowo czytelne klucze błędów dla tej sekcji: INVALID_CURSOR, INVALID_UPDATED_SINCE, DUPLICATE_EXTERNAL_REF, EXTERNAL_REF_TOO_LONG, EXTERNAL_REF_INVALID. Wszystkie odpowiadają HTTP 422 z error_code: "failed" i result.error_key w treści. Opieraj rozgałęzienia na kluczu, nigdy na tekście.
updated_since — Znacznik czasu ISO-8601 (zalecany UTC, np. 2026-09-01T00:00:00Z). Wiersze zaktualizowane w tej chwili lub później. Przełącza polecenie w tryb synchronizacji: stała kolejność (updated_at, id) rosnąco, limit ograniczony do 100.
cursor — next_cursor z poprzedniej odpowiedzi, dosłownie. Jest nieprzezroczysty i podpisany: nigdy go nie buduj ani nie edytuj, nigdy nie używaj ponownie kursora innej firmy ani innego polecenia; wszystkie te przypadki są odrzucane z INVALID_CURSOR.
limit — Rozmiar strony. 1-100 w trybie synchronizacji (domyślnie 10).
next_cursor (odpowiedź) — Kursor następnej strony. null oznacza, że lista jest kompletna; to jedyna poprawna odpowiedź na pytanie „czy jest więcej”.
total (odpowiedź) — Liczba wierszy pasujących do filtrów, niezależnie od strony — do raportowania postępu.
Twój własny klucz: external_ref
Nie rób z naszych autoinkrementowanych identyfikatorów (invoice_id, contact_id) klucza biznesowego w swoim ERP; są nieprzezroczyste i prywatne dla twojej firmy. Ładunki, zapytania transportowe, kontakty, faktury, produkty i magazyny niosą zamiast tego twój klucz.
Ustaw go przy zapisie — loads create, demands create, contacts create i contacts update oraz invoices create przyjmują opcjonalny external_ref (maks. 120 znaków) i zwracają go bez zmian.
Używaj go przy odczycie — loads get --external_ref=ORD-2026-0917, invoices get --external_ref=..., contacts get --external_ref=..., demands get --external_ref=... — wszystkie działają; w poleceniach list i search --external_ref= jest filtrem dokładnego dopasowania.
Unikalny w obrębie firmy — Drugi rekord z tym samym kluczem jest odrzucany z 422 i result.error_key = DUPLICATE_EXTERNAL_REF; klucz innej firmy odpowiada ci „nie znaleziono”. Dopasowanie nie rozróżnia wielkości liter (ord-1 = ORD-1). Zarchiwizowany rekord zachowuje swój klucz; przywróć go, zanim użyjesz tego klucza ponownie.
Wysyłaj też idempotency_key — Ponowienie po przekroczeniu limitu czasu sieci zwraca pierwszy wynik zamiast tworzyć duplikat. Te dwa pola nie są wymienne: external_ref to twój klucz biznesowy, idempotency_key identyfikuje jedną próbę.
Webhooki wychodzące: wysyłamy do ciebie POST, gdy coś się wydarzy
Wszystko do tego miejsca działało w trybie pull: ty pytasz, my odpowiadamy. Most ERP musiał pytać co minutę, żeby dowiedzieć się, że ładunek zmienił status, wystawiono fakturę albo wpłynęła oferta. Już nie: zarejestruj adres https, wybierz zdarzenia, które cię interesują, a gdy się wydarzą, przyjdzie podpisany POST.
Push dodano OBOK pull, a nie zamiast niego. Synchronizacja przyrostowa (updated_since + cursor) pozostaje nietknięta i nadal jest właściwym narzędziem: pierwsze pełne zasilenie, uzupełnianie historii i odpowiedź na pytanie „czy coś mi umknęło” — wszystko to odbywa się tam. Webhooki skracają opóźnienie z minut do sekund. Zdrowy most używa obu — webhooka jako wyzwalacza, synchronizacji jako siatki bezpieczeństwa.
Payload to SYGNAŁ, a nie kopia rekordu. Zawiera identyfikatory (id, twój własny external_ref, status, czas); szczegóły pobierasz własnym kluczem przez GET, a to wywołanie przechodzi już przez twoje własne bramki autoryzacji. Powierzchnia ekspozycji pozostaje więc na poziomie identyfikatorów. Dwóch pól celowo brak: tożsamości firmy, która złożyła ofertę (oferty niejawne pojawiają się w panelu pod aliasem; umieszczenie tożsamości w webhooku przebiłoby tę prywatność drugim kanałem), oraz danych kontaktowych rezerwacji (nie ma potrzeby przesyłać danych osobowych dodatkowym kanałem).
Nazwy zdarzeń są ZAMROŻONE. Jeśli zmienia się znaczenie nazwy, otwierana jest nowa nazwa, a stara żyje przez okno wycofania. Dodanie nowego pola do payloadu NIE podnosi wersji kontraktu — konsument musi ignorować pola, których nie zna.
GET /api/common/integration-webhooks — Rejestr wraz z katalogiem zdarzeń, limitami i nazwami nagłówków. Każdy wiersz zawiera powód wyciszenia i 7-dniowe podsumowanie dostarczeń.
POST /api/common/integration-webhooks — 201 + { webhook, secret, shown_once: true }. Sekret pojawia się tylko tutaj.
PATCH /api/common/integration-webhooks/{uuid} — Nazwa / adres / zdarzenia / flaga aktywności. NIE dotyka sekretu.
DELETE /api/common/integration-webhooks/{uuid} — Usuwa subskrypcję: wiersz jest usuwany miękko (soft delete; historia pozostaje dostępna do zapytań), a oczekujące dostarczenia są anulowane.
POST /api/common/integration-webhooks/{uuid}/rotate-secret — 201 + nowy sekret. Stara wartość przestaje działać w tej samej chwili.
GET /api/common/integration-webhooks/{uuid}/deliveries — Najnowsze dostarczenia: status, numer próby, kod HTTP, czas trwania, znacznik błędu.
POST /api/common/integration-webhooks/deliveries/{uuid}/replay — Ponownie wysyła pojedyncze dostarczenie: event_id jest ZACHOWYWANY, id dostarczenia jest nowe, payload jest kopiowany dosłownie.
Katalog zdarzeń
Za każdym z 13 poniższych zdarzeń stoi klasa zdarzenia, która jest FAKTYCZNIE wysyłana. W katalogu nie ma nazw typu „byłoby miło”: zdarzenie ogłoszone, ale nigdy niewywołane, to zdarzenie, na które integrator czeka w nieskończoność, a ta awaria jest cicha. Ta tabela również nie jest pisana ręcznie — przy każdym załadowaniu strony jest rysowana z bieżącego katalogu.
invoice.payment_recorded jest celowo NIEOBECNE: ta klasa zdarzenia istnieje w kodzie, ale nie jest nigdzie wysyłana. Zdarzenie płatności zostanie dodane w dniu, w którym klasa będzie naprawdę wywoływana — nie wcześniej. Przedwczesne ogłoszenie zdarzenia jest gorsze niż niedodanie go nigdy.
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)
Weryfikacja podpisu
Każde żądanie zawiera nagłówek X-Logistivo-Signature: t=,v1=. Podpisywany ciąg to ".", a algorytm to HMAC-SHA256. Prefiks v1 pozwala wersjonować schemat: jeśli kiedyś pojawi się drugi schemat, nagłówek będzie zawierał t=…,v1=…,v2=…, a ty wybierzesz ten, który znasz.
Publikujemy dwa referencyjne odbiorniki bez zależności, jeden dla Node i jeden dla czystego PHP. Oba stosują cztery powyższe reguły i testują się same przez --selftest: prawidłowy podpis, zmanipulowana treść, zły sekret, znacznik czasu poza oknem, nieprawidłowy nagłówek, pułapka ponownej serializacji i oba rodzaje powtórzeń (to samo dostarczenie / ten sam fakt). Weryfikator jest dokładnym odpowiednikiem kodu, którego sami używamy — korzystamy z kontraktu, który publikujemy.
Weryfikuj SUROWĄ treść — Podpis jest liczony z bajtów. Dekodowanie i ponowna serializacja treści (JSON.stringify(req.body), json_encode($request->all())) zamienia te same DANE w inne BAJTY i podpis przestaje się zgadzać. W Node pułapką jest formatowanie liczb (1.50 w transmisji staje się 1.5; duże liczby całkowite tracą precyzję), w PHP — escapowanie znaków (/ staje się \/, İ staje się İ). Używaj express.raw w Express i $request->getContent() w Laravel. To najczęstszy błąd przy pisaniu odbiornika.
Sprawdzaj znacznik czasu — t jest WEWNĄTRZ podpisu. Weryfikacja samego podpisu pozwala każdemu, kto przechwycił prawidłowe żądanie, odtworzyć je kilka godzin później, a odbiornik uznałby je za zweryfikowane zdarzenie. Odrzucaj każde żądanie, dla którego |now − t| > tolerancja, nawet jeśli podpis jest poprawny. Zalecane okno to 300 s.
Porównuj w stałym czasie — hash_equals / timingSafeEqual. Porównanie przez == pozwala atakującemu odgadywać podpis bajt po bajcie.
Deduplikuj po event_id, a nie po id — event_id identyfikuje FAKT: jest taki sam dla dwóch subskrybentów otrzymujących to samo zdarzenie i jest ZACHOWYWANY przy ponownym wysłaniu (replay). id (= X-Logistivo-Delivery) identyfikuje DOSTARCZENIE i zmienia się przy ponownym wysłaniu. Na pytanie „czy to zostało już obsłużone” odpowiadaj za pomocą event_id; odpowiadanie za pomocą id sprawia, że ponowne wysłanie wykona tę samą pracę dwa razy.
Dostarczanie, ponowienia i wyciszanie
Twój odbiornik nie zawsze będzie dostępny. Mechanizm to zakłada: przejściowa awaria trafia do harmonogramu ponowień, trwała wycisza subskrypcję — a POWÓD wyciszenia jest zawsze zapisywany.
Powód wyciszenia jest maszynowo czytelny i stabilny (delivery_failures, endpoint_gone, unsafe_target, key_revoked, by_user) i widać go zarówno w panelu, jak i w `lg webhooks list`. Wyciszenie bez powodu sprawiłoby, że na pytanie „dlaczego nic nie przychodzi” nie byłoby odpowiedzi. Ponowne włączenie zeruje licznik i znacznik.
Adres piszesz ty; żądanie wykonuje NASZ serwer. Bez bramki tenant, który wpisałby adres metadanych chmury, mógłby zmusić nas do wysyłania żądań z wnętrza naszej własnej sieci. Dlatego adres jest sprawdzany zarówno przy rejestracji, jak i przy KAŻDYM dostarczeniu:
Limity czasu — 8 s łącznie, 4 s na połączenie — wolny odbiornik nie może blokować workera. Wstaw pracę do kolejki i od razu zwróć 2xx.
Harmonogram ponowień — 60 · 300 · 1800 · 7200 · 21600 s → łączna liczba prób: 6, okno około 8,6 h.
Jedyna trwała awaria: 410 Gone — Oznacza „usuń mnie”: bez ponowień, subskrypcja jest natychmiast wyciszana. NIGDY nie zwracaj 410 przy błędzie podpisu.
Każda inna awaria — WSZYSTKIE są ponawiane, łącznie z 4xx. Utrata zdarzenia biznesowego kosztuje więcej niż kilka dodatkowych żądań: odbiornik zwracający 403 w trakcie aktualizacji reguły WAF po cichu straciłby zdarzenie „faktura wystawiona” w mechanizmie, który traktuje 4xx jako trwałe.
Retry-After — Respektowany przy 429 i 503 (maksymalnie 6 godzin).
Przekierowania — NIE są wykonywane. Przeskok na adres wewnętrzny przez 302 przebiłby bramkę adresów drugą drogą.
Automatyczne wyciszanie — Po 10 kolejnych dostarczeniach, które wyczerpały ponowienia. 410, niebezpieczny cel oraz unieważnienie powiązanego klucza integracyjnego wyciszają NATYCHMIAST.
tylko https, tylko porty 443/8443, osadzone dane uwierzytelniające (https://user:pass@…) są odrzucane;
localhost, nazwy jednoczłonowe i wewnętrzne sufiksy, takie jak .internal / .local / .svc, są odrzucane — intencja jest odrzucana, zanim w ogóle spojrzymy na wynik rozwiązywania nazwy, więc split-horizon DNS nie przebije bramki;
literały IP i WSZYSTKIE rekordy z rozwiązania DNS muszą być publiczne. Jeśli nazwa rozwiązuje się zarówno na adres publiczny, jak i prywatny, nikt nie pyta nas, który wybrać → nazwa jest od razu odrzucana;
w chwili dostarczenia adres jest rozwiązywany raz, a połączenie jest przypinane do zweryfikowanego adresu: okno na DNS rebinding jest zamknięte;
TREŚĆ odpowiedzi odbiornika nigdy nie jest nigdzie przechowywana (tylko kod statusu, czas trwania i krótki znacznik błędu) — więc ścieżka „odczytu”, która jest tym, co naprawdę daje dziura w bramce adresów, pozostaje zamknięta.
Celowo NIE ma przełącznika konfiguracyjnego „zezwalaj na adresy prywatne”: taki przełącznik pewnego dnia zostaje przez przypadek włączony.
Zwracany JEDEN raz, tylko przy tworzeniu subskrypcji i przy rotate-secret. Jest przechowywany na serwerze w postaci zaszyfrowanej i nigdy nie da się go odczytać; nie ma opcji „pokaż ponownie”.
lg wypisuje go na ekran i na tym poprzestaje — nie zapisuje go w żadnym pliku konfiguracyjnym ani pliku pamięci podręcznej.
Jeśli zostanie utracony, wykonujesz rotację; stara wartość przestaje działać W TEJ SAMEJ CHWILI. Aby przełączenie było płynne, twój odbiornik powinien w okresie przejściowym sprawdzać oba sekrety.
Zmiana adresu NIE dotyka sekretu: rutynowa konserwacja w rodzaju „URL się przeniósł” nie może psuć weryfikacji po stronie odbiorcy.
Stan i status: nikt nie powinien zauważyć cichego mostu przed tobą
Most integracyjny rzadko umiera z hukiem. Zwykle cichnie nad ranem: wygasa token, osoba, w imieniu której działa klucz, odchodzi z zespołu, zakres zostaje zawężony albo endpoint odbierający zaczyna zwracać 403. Pierwszy zauważa to prawie zawsze klient. lg status istnieje po to, by odwrócić tę kolejność.
Jedno polecenie odpowiada na dwa pytania naraz, bo podczas awarii oba padają w tej samej chwili: czy platforma działa i czy mój most jest zdrowy. Linia platformy działa bez tokenu — podczas awarii to właśnie token jest pierwszym podejrzanym, a uzależnienie od niego pytania o status zostawiłoby cię bez odpowiedzi dokładnie wtedy, gdy jej potrzebujesz.
Podsumowanie stanu nie prowadzi nowego rejestru; składa w jedno zdanie trzy istniejące źródła: dzienny licznik użycia (ile wywołań i ile nieudanych), rejestr żądań (które żądanie, kiedy i dlaczego zostało odrzucone) oraz rejestr dostarczeń webhooków wychodzących (czy zdarzenie dotarło do odbiornika). Współczynnik błędów jest zawsze odczytywany z dziennego licznika; rejestr szczegółowy ma limit i wyraźnie to komunikuje, gdy limit zostanie osiągnięty.
To samo podsumowanie pojawia się w panelu: w Settings › Integration › Keys każdy wiersz ma plakietkę, a pod nią powód. Progi nie są liczone po stronie klienta; poziom przypisany przez serwer jest tym, co rysują zarówno panel, jak i lg status, więc dwa ekrany nigdy nie mogą mówić różnych rzeczy o tym samym kluczu.
Twój watchdog nie potrzebuje tokenu. Endpoint zwraca tylko słowa statusu; nie zawiera wersji, nazwy hosta, nazwy kolejki, liczby zadań, tekstu błędu ani danych klientów — i nie może ich zawierać.
Podsumowanie stanu powstaje przy stałej liczbie zapytań na żądanie; liczba zapytań nie rośnie wraz z liczbą kluczy. Po szczegóły sięgnij do ostatnich żądań danego klucza przez lg logs, a do mostu wychodzącego — przez lg webhooks list.
SPRAWNY — Brak zmierzonej usterki i mamy dowód sukcesu: udane wywołanie w rejestrze lub ruch, który w liczniku pozostał bez błędów.
UWAGA — Coś zaczęło się psuć: współczynnik błędów lub seria kolejnych niepowodzeń przekroczyły próg, żądania są odrzucane na bramce, klucz zbliża się do wygaśnięcia albo most, który odzywał się regularnie, ucichł.
AWARIA — Most w tej chwili nie działa: token został unieważniony niezamierzenie, zamknięty klucz jest wciąż wywoływany, wystąpiło pięć niepowodzeń z rzędu, współczynnik błędów przekracza pięćdziesiąt procent albo subskrypcja webhooka została wyciszona.
ZAMKNIĘTY — Klucz został zamknięty celowo i nikt go nie wywołuje. To decyzja, a nie usterka — i nie jest malowana na czerwono.
BRAK DANYCH — Nie ma pomiaru: klucz nigdy nie był wywołany albo sam pomiar się nie powiódł. Żaden z tych przypadków nie jest zielony.
Żadnej fałszywej zieleni. Plakietka SPRAWNY wymaga zmierzonego dowodu sukcesu; klucz, który nigdy nie był wywołany, nigdy nie zmienia się na zielony, bo żaden pomiar nie pokazuje, że działa.
Żadnej fałszywej czerwieni. Klucze zamknięte celowo są pokazywane jako ZAMKNIĘTY. Malowanie wszystkiego na czerwono odbiera czerwieni znaczenie; zamknięty klucz staje się czerwony tylko wtedy, gdy nadal jest wywoływany po zamknięciu — a wtedy most naprawdę jest zepsuty.
„Nie udało się zmierzyć” to nie to samo co „brak danych”. Jeśli zapytanie zawiedzie po stronie serwera, wiersz nie pokazuje po cichu zera; mówi, że pomiaru nie dało się wykonać.
Cisza jest zawsze raportowana, ale nigdy nie zamienia się na ślepo w ostrzeżenie. Most działający na koniec miesiąca, który milknie na trzydzieści godzin, to norma; most, który odzywał się w co najmniej pięciu z ostatnich siedmiu dni, a ucichł, to usterka. Rytm jest mierzony, a nie zakładany.
Samo zapytanie o status nie zaburza liczb o stanie. Wywołania wykonane przez lg status pojawiają się w rejestrze żądań, ale są wyłączone z obliczeń stanu — w przeciwnym razie twoje własne udane zapytanie o status zerowałoby serię niepowodzeń i ukrywało dokładnie tę usterkę, którą ekran ma pokazywać.
Każda linia jest mierzona: na bazie danych wykonywane jest prawdziwe zapytanie, katalog poleceń jest naprawdę budowany, a bieżący zapis workera kolejki jest naprawdę odczytywany. Nic nie jest zakładane.
Sama odpowiedź też jest pomiarem: jeśli możesz odczytać treść, warstwa webowa działa.
Najwyższy poziom wynika wyłącznie z wymaganych komponentów. Gdy kolejka staje, odpowiedź brzmi degraded, a nie down — synchroniczne wywołanie API nie potrzebuje kolejki, a ogłoszenie, że platforma nie działa, byłoby fałszywym alarmem.
Gdy stanu kolejki nie da się zmierzyć, najwyższy poziom pozostaje nienaruszony: niewiedza to nie to samo co zmierzenie, że coś jest zepsute.
Jeśli platforma nie działa, endpoint zwraca HTTP 503. Treść nie ma koperty, aby narzędzia monitorujące mogły alarmować bez jej parsowania, a odpowiedź nigdy nie jest przechowywana w żadnej pamięci podręcznej.
Błędy i kody wyjścia
To, na czym maszyna opiera rozgałęzienia, jest stabilnym ciągiem znaków. Tekst w polu error jest przeznaczony dla człowieka, jest zlokalizowany i zmienia się bez uprzedzenia — integracja, która opiera rozgałęzienia na tekście komunikatu, nie jest wspierana, a jej zepsucie się nie jest błędem.
Dwie taksonomie, dwa pola. error_code to warstwa transportowa (tabela powyżej) i to na nim opierasz rozgałęzienia w pierwszej kolejności. error_key to stabilny klucz reguły biznesowej wewnątrz failed — INSUFFICIENT_CREDITS, NOT_FOUND, DUPLICATE_CONTACT, INSUFFICIENT_STOCK — publikowany jako słownik w katalogu (error_keys) i poniżej. Polecenie, które jeszcze nie emituje klucza, zwraca error_key: null; klucz nieobecny w słowniku traktuj jak ogólne niepowodzenie.
ok — HTTP 200 · error_code — · CLI 0 · —
replayed — HTTP 200 · error_code — · CLI 0 · Odtworzenie idempotentne; praca NIE została wykonana ponownie.
failed — HTTP 422 · error_code failed · CLI 1 · Nie — odrzuciła je reguła biznesowa (zob. error_key). Nie ma sensu, dopóki argument się nie zmieni.
needs_confirmation — HTTP 409 · error_code needs_confirmation · CLI 4 · Tak, z confirm: true.
idempotency_conflict — HTTP 409 · error_code idempotency_conflict · CLI 2 · Nie — klucz został najpierw użyty z innym poleceniem (conflicting_command). Wygeneruj nowy klucz.
forbidden — HTTP 403 · error_code forbidden · CLI 3 · Nie — bramka ról albo klucz z zakresem odczytu w poleceniu zapisującym.
not_found — HTTP 404 · error_code not_found · CLI 2 · Nie — błędna lub usunięta nazwa polecenia.
(schemat) — HTTP 422 · error_code invalid_request · CLI 2 · Nie — treść żądania lub argument nie przeszły walidacji schematu (errors{}); to nie reguła biznesowa.
server_error — HTTP 500 · error_code server_error · CLI 6 · Tak — wykładnicze wydłużanie odstępów z TYM SAMYM kluczem idempotencji; klucz nie został zablokowany.
401 unauthenticated — Token wygasł lub został unieważniony. Ponawianie nie pomoże; token trzeba wymienić.
429 rate_limited — Przekroczono limit żądań dla tego tokenu. Odpowiedź zawsze zawiera Retry-After oraz treść z retry_after, limit i bucket; respektuj ją zamiast wymyślać stałe opóźnienie. lg czeka i ponawia do trzech razy, a potem kończy działanie z kodem 5.
5xx server_error / błąd sieci — Ponów z wykładniczym wydłużaniem odstępów i TYM SAMYM kluczem idempotencji. Zmiana klucza ponownie uruchamia pracę, którą serwer mógł już wykonać. lg ponawia trzy razy (1 s, 2 s, 4 s), a potem kończy działanie z kodem 6 i error_code network_error lub server_error.
Obietnica stabilności
Najdroższe pytanie w kontrakcie integracyjnym brzmi: „czy kod, który piszę dziś, będzie działał jutro?”. Odpowiada na nie jedna liczba: contract_version w katalogu i nagłówek X-Contract-Version w każdej odpowiedzi. Odpowiada ona dokładnie na jedno pytanie — czy wcześniej napisany kod nadal działa bez zmian? Jeśli liczba nie wzrosła — tak. Jeśli wzrosła — nie: coś, na czym opierał się twój kod, zostało usunięte lub zawężone.
Bo ogłoszenie niczego nie usuwa: twój istniejący kod działa dokładnie tak jak wcześniej, także dzień później. Podnoszenie wersji przy ogłoszeniu dałoby dwa sygnały dla jednej zmiany i nauczyłoby cię ignorować pierwszy — osłabiając sygnał, który naprawdę ma znaczenie. Ogłoszenie i tak dociera wraz z wywołaniem, które wykonujesz: deprecated_at i replaced_by w wierszu katalogu, nagłówek X-Deprecated plus blok deprecated w odpowiedzi tego polecenia oraz jednowierszowe ostrzeżenie na stderr, jeśli używasz lg. Nie musisz nic robić, by dowiedzieć się, że coś zniknie; to już jest w twoim logu.
Między ogłoszeniem a usunięciem mijają co najmniej dwa kwartały kalendarzowe. Przez całe okno stare polecenie nadal odpowiada i ostrzega przy każdym wywołaniu. Gdy nazwa CLI zostaje wycofana, jej następca przejmuje tę nazwę jako alias: w trakcie okna stara nazwa trafia do starego polecenia, a w dniu usunięcia to samo wywołanie trafia do nowego — bez wydawania przez ciebie nowej wersji klienta.
preview_invoice → get_invoice (ogłoszone 3 września 2026). get_invoice zwraca ten sam blok podglądu i dodaje pozycje, rozbicie podatków, zarejestrowane płatności, saldo pozostałe do zapłaty oraz adresowanie twoim własnym kluczem ERP (external_ref). preview_invoice nadal działa, podobnie jak lg invoices preview — oba ostrzegają.
bez zmian — Nowe polecenie · nowy OPCJONALNY parametr · nowe pole odpowiedzi · nowy klucz błędu · nowy endpoint — Nic nie rób. Musisz ignorować pola, których nie znasz; parser, który zawodzi na nieznanym polu, jest niezgodny z kontraktem.
bez zmian — OGŁOSZENIE wycofania: zapowiedź, że polecenie zniknie — Twój kod działa dalej. Wpisz zadanie do kalendarza — okno wynosi co najmniej 6 miesięcy.
rośnie — Usunięcie polecenia · wycofanie starej nazwy CLI · usunięcie pola odpowiedzi · zmiana parametru opcjonalnego na wymagany · zawężenie enuma — Oznacza to, że okno zostało przegapione; zapowiedź dotarła do ciebie w trzech różnych miejscach.
Nazwa API polecenia (np. list_loads) jest zamrożona na zawsze; to jej używasz w wywołaniach HTTP.
error_code (transport) i error_key (reguła biznesowa) to stabilne ciągi znaków. Mogą pojawić się nowe — klucz, którego nie znajdziesz w słowniku, traktuj jak ogólne niepowodzenie, a nie jak zerwanie kontraktu.
Odwzorowanie między statusem HTTP a polem status w treści jest stałe.
Numer wersji nigdy nie maleje i można go odczytać z każdej odpowiedzi — także z 304 i 429 bez treści.
TEKST błędów i opisów. Jest zlokalizowany i zmienia się bez uprzedzenia; rozgałęzianie na podstawie tekstu komunikatu nie jest wspierane.
Brak pól, których nie znasz. Dodanie pola nie podnosi wersji.
Autoinkrementowane identyfikatory jako klucze biznesowe. Przekazuj własny klucz przez external_ref.
Dynamiczne klucze błędów wyprowadzane z nazw klas; nie są częścią kontraktu.
Tabela tożsamości poleceń
Poniższa tabela nie jest pisana ręcznie: jest generowana z bieżącego rejestru poleceń za każdym razem, gdy ta strona jest serwowana. Polecenie dodane na serwerze pojawia się tu samo. Kolumna „Bramka” mówi, czy polecenie prosi o potwierdzenie i czy jego efekt można cofnąć; kolumna „Role” mówi, które typy kont znajdą je w swoim katalogu. Plakietki oznaczają polecenia wymagające klucza na poziomie manager, polecenia przyjmujące plik oraz te, które działają tylko z lg.
Polecenia są pogrupowane według funkcji, każda na osobnej stronie. Wybierz funkcję, aby otworzyć jej tabelę poleceń.
Nazwa API (list_loads) jest zamrożona i nie zmieni się; to jej używasz w wywołaniach HTTP. Tożsamość CLI (loads list) podlega polityce wersjonowania: po ogłoszeniu zmienia się tylko wraz z podniesieniem wersji i oknem migracji, w trakcie którego katalog serwuje starą parę jako alias. Opisy tutaj pochodzą z własnego rekordu każdego polecenia i są skrócone — pełny tekst, typy parametrów i wartości enum znajdziesz w endpoincie katalogu albo po uruchomieniu lg help . Polecenia dostępne tylko dla afiliantów nie są tu wymienione; konto afilianta widzi je we własnym katalogu.
Ładunki i śledzenie — Tworzenie ładunków, uczestnicy, dokumenty, linki do śledzenia, podpis odbioru, ETA i wyjątki. Polecenia: 115 — /pl/developers/cli/loads
Granica i cło — Kontrola gotowości do granicy, oczekiwanie na granicach i w portach, dokumenty eksportowe, zgłoszenie U-ETDS. Polecenia: 42 — /pl/developers/cli/border
Zapytania i oferty — Otwieranie zapytań transportowych, zbieranie i składanie ofert, przetargi, przewoźnicy w sieci. Polecenia: 42 — /pl/developers/cli/quotes
Cenniki i oferty sprzedaży — Uzgodnione cenniki, kaskada ofert i oferty sprzedaży dla Twoich klientów. Polecenia: 57 — /pl/developers/cli/pricing
Flota i kierowcy — Kierowcy, pojazdy, paragony wydatków, rozliczenia kierowców, planowanie tras i dni Schengen. Polecenia: 115 — /pl/developers/cli/fleet
Magazyn i zapasy — Magazyny, rezerwacje, awizacje na rampę, ekran bramy, produkty, zapasy i palety. Polecenia: 69 — /pl/developers/cli/warehouse
Księgowość i faktury — Faktury, kontrola faktur zakupowych, Paraşüt, zapisy księgowe, wpływy i płatności, marże. Polecenia: 95 — /pl/developers/cli/finance
Wiadomości i e-mail — Czaty ładunków, wiadomości bezpośrednie, szkice i skrzynki e-mail, powiadomienia. Polecenia: 58 — /pl/developers/cli/messages
Taryfa celna i środki handlowe — Wyszukiwanie kodów HS, cła importowe, środki antydumpingowe, raporty emisji. Polecenia: 20 — /pl/developers/cli/tariffs
Firmy i zespół — Katalog firm, relacje i dokumenty, spółki zależne, członkowie zespołu i zaproszenia. Polecenia: 65 — /pl/developers/cli/contacts
Automatyzacja i raporty — Reguły automatyzacji, raporty niestandardowe, pliki Excel i PDF, plany pracy. Polecenia: 27 — /pl/developers/cli/automation
Konto i integracja — Ustawienia konta i języka, klucze integracji, pakiet, kredyty i portfel. Polecenia: 16 — /pl/developers/cli/account
Integracja z ERP i CRM — Tożsamość: żadnych kont serwisowych, zamiast tego prawdziwy użytkownik
ERP lub CRM łączy się z Logistivo jako prawdziwy użytkownik firmy, posiadający osobisty token dostępu wygenerowany w panelu. Syntetyczne konto serwisowe — bez firmy, wyłączone z ograniczania zakresu, bez nikogo odpowiedzialnego — nigdy nie jest tworzone.
To architektura, a nie preferencja. Izolacja multi-tenant opiera się w całości na firmie użytkownika; dla tożsamości bez firmy zakres izolacji przestaje działać, a jedno błędne zapytanie z takim tokenem odczytuje dane, które do niego nie należą. Drugim powodem jest audyt: kolumna użytkownika w rejestrze wiąże „kto to uruchomił” z osobą; konto serwisowe czyni tę kolumnę bezużyteczną i zostawia integrację wystawiającą faktury bez właściciela. Trzecim jest unieważnianie: jeśli token należy do osoby, integracja milknie, gdy ta osoba odchodzi. Most bez właściciela to most, który latami po cichu dalej zapisuje.
W praktyce: firma tworzy w panelu zwykłego użytkownika (np. „ERP Bridge”, którego właścicielem jest konkretny, wskazany z imienia i nazwiska pracownik), nadaje mu wąską rolę, generuje token z sesji tego użytkownika i umieszcza go w ERP.
Ten użytkownik jest widoczny w systemie uprawnień, jego prawa można ograniczyć, a jego token można unieważnić niezależnie. Zabronione nie jest tworzenie konta — zabronione jest tworzenie konta niezwiązanego z tenantem.
Jedna integracja na token. Jeśli dwa systemy współdzielą token, znika szczegółowość unieważniania: odcięcie CRM oznacza też odcięcie ERP.
Integracja z ERP i CRM — Wersjonowanie i wycofywanie
Odpowiedź katalogu zawiera liczbę całkowitą contract_version; wiersze poleceń zawierają since, deprecated_at i replaced_by. Wersja kontraktu rośnie tylko przy zmianach łamiących zgodność.
Wersja NIE rośnie przy: nowym poleceniu, nowym opcjonalnym parametrze, nowym polu w odpowiedzi. Konsument musi ignorować pola, których nie zna; klient, który zgłasza błąd na nieznanym polu, jest niezgodny z kontraktem.
Wersja ROŚNIE przy: usunięciu lub zmianie nazwy polecenia, usunięciu pola odpowiedzi, zmianie parametru opcjonalnego na wymagany, zawężeniu enuma. Stary kształt pozostaje aktywny przez co najmniej dwa kwartały kalendarzowe (6 miesięcy) z deprecated_at i replaced_by.
Wycofanie jest ogłaszane w katalogu, a nie tylko w changelogu. Ponieważ klient rysuje się na podstawie katalogu, polecenie z ustawionym deprecated_at wypisuje ostrzeżenie bez żadnego nowego wydania klienta, a integrator widzi je w swoich logach.
Nazwa API jest zamrożona na zawsze. Tożsamość CLI (domena/czasownik) można było swobodnie przycinać przed jej ogłoszeniem; po ogłoszeniu zmienia się tylko z podniesieniem wersji i oknem migracji, w trakcie którego stara para jest serwowana jako alias.
W praktyce: odpowiedź katalogu i nagłówek X-Contract-Version niosą wersję; każdy wiersz polecenia zawiera since, deprecated_at, replaced_by i aliases (stare pary domena/czasownik). Wywołanie wycofywanego polecenia nadal działa i odpowiada z nagłówkiem X-Deprecated: name; deprecated_at=…; replaced_by=… oraz obiektem deprecated w treści. ?domain= w katalogu rozwiązuje starą domenę-alias na bieżące polecenie.
Klient, który rozumie wersję 1 i napotka większą liczbę, powinien zapisać ostrzeżenie w logu i działać dalej; lg robi dokładnie to. Obowiązujące wycofania są wymienione w obietnicy stabilności powyżej.
Integracja z ERP i CRM — Stabilne identyfikatory: nigdy nie przekazuj swojemu ERP autoinkrementowanego id jako klucza
Wewnętrzne autoinkrementowane identyfikatory są nieprzezroczyste i ograniczone do tenanta: prawidłowy identyfikator innej firmy zwraca ci „nie znaleziono”, a nie dane. Ale nieprzezroczystość nie czyni z nich kluczy biznesowych. To, co ERP przechowuje we własnym rekordzie, musi być kluczem biznesowym.
Ładunek: code (kod klienta, np. FSK2158). loads get już działa po kodzie.
Kraj: ISO 3166-1 alpha-2. countries search zwraca ten kod.
HS / taryfa: sam kod — nomenklatura jest już uniwersalna.
Faktura: numer faktury, po jej wystawieniu. Szkic ma tylko identyfikator techniczny, a identyfikator szkicu NIE jest kluczem biznesowym — ERP powinien przechowywać własną referencję i nigdy nie utrwalać identyfikatora szkicu.
Produkt, magazyn, kontakt: dziś tylko identyfikator techniczny. Reguła dla nowych poleceń jest jednoznaczna: każde polecenie zwracające identyfikator techniczny zwraca też własny klucz biznesowy tenanta (SKU, kod, numer podatkowy), aby ERP mógł dopasować rekordy po swojej stronie.
Integracja z ERP i CRM — Paginacja, filtrowanie i synchronizacja przyrostowa
Polecenia listujące przyjmują limit i zwracają count. Na potrzeby nocnej synchronizacji kontrakt zobowiązuje się do poniższego; polecenie listujące, które to wdrożyło, ogłasza cursor i updated_since w swoim JSON Schema, a dopóki tego nie zrobi, traktuj je jako małe okno (maksymalnie 20 wierszy, bez kursora).
Żądanie: limit (od 1 do limitu danego polecenia) plus cursor (nieprzezroczysty, tylko do przodu, podpisany przez serwer). offset NIE jest używany — w żywej tabeli offset się przesuwa; rekord wstawiony między dwiema stronami sprawia, że ERP pomija wiersz albo liczy go dwa razy, i dzieje się to po cichu.
Odpowiedź: { count, total?, next_cursor|null }. count to liczba wierszy w tej odpowiedzi; gdy next_cursor jest null, lista jest kompletna. Przekazuj next_cursor z powrotem bez zmian — to nie jest numer strony i nie do ciebie należy jego budowanie.
Zmanipulowany lub obcy kursor jest odrzucany z 422 invalid_request; kursor jest związany z firmą, która go otrzymała, i nie pozwala stronicować danych innego tenanta.
Filtrowanie: nazwane parametry w JSON Schema, łączone przez AND. Nie ma swobodnego języka zapytań — DSL byłby drugą powierzchnią zapytań, której musielibyśmy bronić.
Synchronizacja przyrostowa: updated_since (ISO-8601, UTC) plus kursor. Zapisz najnowszą zaobserwowaną wartość updated_at i przekaż ją przy następnym przebiegu; bez tego każdy ERP co godzinę pobiera wszystko od nowa.
Referencja zewnętrzna: polecenia zapisujące przyjmują external_ref (twój własny klucz dokumentu), unikalny w obrębie firmy; drugie utworzenie z tym samym external_ref jest odrzucane, a nie duplikowane, a list/get go zwracają, aby dało się dopasować rekordy po twojej stronie.
Integracja z ERP i CRM — Limity żądań
Kluczem limitu jest token, a nie IP: ERP przychodzi zza jednego NAT-u, a limit oparty na IP liczyłby całą firmę jako jednego użytkownika. Dwie integracje z dwoma kluczami nigdy nie zjadają sobie nawzajem limitu — to drugi powód zasady „jedna integracja na klucz”.
Wykrywanie bez uwierzytelnienia (public/cli/catalog): 30 na minutę. To słownik, a nie źródło danych; przeczytaj go raz podczas pisania mostu, nigdy w pętli produkcyjnej.
Endpointy katalogu (GET common/commands, GET common/commands/{name}): 120 na minutę na token. Katalog rzadko się zmienia i odpowiada 304 na If-None-Match; nie pobieraj go ponownie przed każdym poleceniem — lg przechowuje go w pamięci podręcznej przez godzinę.
Polecenia odczytu (POST common/commands/{name} z read_only: true): 120 na minutę na token.
Polecenia zapisujące (POST common/commands/{name} z read_only: false; nieznana nazwa też jest liczona tutaj): 30 na minutę na token. Zapisy mają skutki uboczne; za niekontrolowaną pętlę się płaci.
Polecenia zużywające kredyty (credit_cost w wierszu katalogu nie jest zerem — na przykład tariffs inquiry i export-documents generate): rzeczywistym limitem są KREDYTY, a nie liczba żądań. Odpowiedź 200 mogła zużyć kredyt.
Dzienne limity na firmę, wspólne z panelem: polecenia wysyłające e-mail lub push do osób spoza twojej firmy korzystają z puli 300 powiadomień wychodzących dziennie, a uruchamianie płatnego śledzenia kontenerów lub statków — z puli 100 dziennie. Po przekroczeniu limitu polecenie odpowiada DAILY_LIMIT_REACHED z retry_after; przesyłanie plików ma własne limity (zob. Polecenia przyjmujące pliki).
429 zawsze zawiera Retry-After oraz treść { error_code: "rate_limited", retry_after, limit, bucket }; respektuj ją zamiast wymyślać stałe opóźnienie. Katalog publikuje aktualne wartości pod rate_limits.
Integracja z ERP i CRM — Czego nie zrobimy
To często najbardziej przydatna część kontraktu: wiedza o tym, co nigdy nie nadejdzie, pozwala zaprojektować rozwiązanie z uwzględnieniem tego.
Żadnego konta serwisowego ani podmiotu niezwiązanego z tenantem.
Żadnych płatności, numerów kart ani zgód prawnych przez API lub czat. Te kroki pozostają w przeglądarce danej osoby; polecenie przekazuje ci link.
Żadnej drugiej ścieżki: nie ma bezpośredniego dostępu do bazy danych, dostępu do powłoki ani endpointu masowego, który omijałby jedyny punkt egzekwowania. Bramka ról, bramka potwierdzenia, idempotencja i rejestr audytu są egzekwowane tylko tam.
Rozgałęzianie na podstawie tekstu komunikatu o błędzie nie jest wspierane; tekst jest zlokalizowany i zmienia się bez uprzedzenia.
Żadnej paginacji offsetowej.
Używanie identyfikatora technicznego jako klucza biznesowego w twoim ERP nie jest wspierane.
Webhooki wychodzące nie są wciskane w ten kontrakt — ale teraz ISTNIEJĄ i są opisane na tej stronie (sekcja o webhookach powyżej). Katalog to powierzchnia typu PULL, a strumień zdarzeń to OSOBNY kontrakt: nazwy zdarzeń i schemat payloadu są wersjonowane według własnych reguł i nie są powiązane z wersją kontraktu katalogu poleceń.
Katalog do odczytu maszynowego
Ta strona została napisana dla ludzi. Dla asystenta AI lub zautomatyzowanego klienta te same informacje istnieją jako ustrukturyzowana kopia dostępna bez uwierzytelnienia.
GET /api/public/cli/catalog nie wymaga uwierzytelnienia i zwraca publiczną tożsamość poleceń: zamrożoną nazwę API, tożsamość CLI domena/czasownik, opis, parametry JSON Schema, flagi read_only, confirmation_needed i irreversible, credit_cost oraz pola dostępu key_level, permission, file_params, secret_parameters i cli_only. Nie zwraca żadnych danych osobowych, danych tenantów ani przykładowych rekordów — tylko to, czym jest ta powierzchnia.
Właściwy sposób korzystania z niego przez zewnętrznego agenta: przeczytać katalog, wyjaśnić WŁASNYMI słowami, jakie zadania są możliwe, a gdy potrzebne jest wykonanie — wskazać użytkownikowi, jak uruchomić polecenie we własnym środowisku z własnym tokenem. Agent nigdy nie prosi o token użytkownika, nie generuje go ani go nie przekazuje.
Podłączenie Logistivo do asystenta AI w celu rejestracji i składania zapytań transportowych to osobny kanał z własną stroną:
Katalog jest dostępny bez uwierzytelnienia; wykonanie — nie. Nie ma sposobu na uruchomienie polecenia w imieniu agenta — to, co się wykonuje, działa zawsze z własną tożsamością użytkownika.
Hasło do Logistivo, kod weryfikacyjny ani token dostępu nigdy nie przechodzą przez czat. Nie buduj przepływu, który o nie prosi, generuje je lub je przekazuje.
To, czy polecenie jest nieodwracalne, jest zapisane w katalogu. Nigdy nie proponuj „spróbujmy” w przypadku polecenia z irreversible: true.
Polecenia, których credit_cost nie jest zerem (na przykład tariffs inquiry i export-documents generate), mają skutek pieniężny; nie wywołuj ich w zautomatyzowanej pętli.
Płatności, numery kart i zgody prawne nigdy nie przechodzą przez czat ani agenta. Zamiast tego zaproponuj link z handoff-links generate; osoba kończy krok we własnej przeglądarce.
Agent działający kluczem użytkownika powinien najpierw wywołać users get — to polecenie zwraca rolę, poziom dostępu klucza, efektywne uprawnienia oraz informację, czy oczekująca zgoda lub weryfikacja telefonu blokuje zapisy. Przewiduj odmowy, zamiast je zbierać.
Wersja tekstowa tej strony znajduje się pod /cli.md; korzystaj z niej, jeśli markdown parsujesz pewniej niż HTML.
Definicja do odczytu maszynowego: OpenAPI 3.1 i Postman
Powyższy katalog to własny format Logistivo. Te same informacje są też publikowane w dwóch standardowych formatach branżowych, które twoje narzędzia już rozumieją: jako definicja OpenAPI 3.1 i jako kolekcja Postman. Żadna z nich nie jest pisana ręcznie — obie są generowane z bieżącego rejestru poleceń przy każdym żądaniu, więc nie mogą się zdezaktualizować.
Definicja JEST katalogiem, a nie drugą rzeczywistością. Każde polecenie występuje jako operacja POST /api/common/commands/; schemat treści to własny JSON Schema polecenia (bajt w bajt to, co widzi asystent), schemat odpowiedzi to wspólna koperta, flagi bramek (read_only, confirmation_needed, irreversible i plakietka kredytów) znajdują się w rozszerzeniu x-logistivo, a biznesowe klucze błędów — pod x-error-keys. Wycofane polecenie jest oznaczone jako deprecated: true i pozostaje wywoływalne przez sześciomiesięczne okno.
Obok powierzchni poleceń w definicji są też endpointy REST, które niosą kontrakt integracyjny: endpointy listujące z synchronizacją przyrostową (updated_since + cursor + limit) w liczbie 10 oraz endpointy zapisu przyjmujące twój własny klucz (external_ref) w liczbie 7. Powierzchnia REST Logistivo jest znacznie większa; resztę pominięto CELOWO. Te payloady są własnym kontraktem produktu, a schemat napisany na podstawie domysłów zepsułby twojego wygenerowanego klienta przy pierwszym wywołaniu — a błędu szukałoby się w twoim kodzie, nie w naszym.
Definicja jest generowana dla ROLI pytającego: polecenie innej roli nigdy nie trafia do dokumentu, bo definicja jest kontraktem, a nie słownikiem, i wszystko w niej musi być wywoływalne tym tokenem. Wersja bez uwierzytelnienia to suma trzech ról i tam każda operacja podaje pod x-logistivo.roles, które role ją widzą.
Nie wierz nam na słowo — sprawdź: npx @redocly/cli lint logistivo-openapi.json przechodzi bez żadnych ostrzeżeń.
GET /api/common/spec/openapi.json — Definicja OpenAPI 3.1 dla roli twojego tokenu. Zawiera ETag; If-None-Match daje 304, więc nie pobierasz jej ponownie przy każdym buildzie.
GET /api/common/spec/postman.json — Ten sam zakres jako kolekcja Postman v2.1, ze zmiennymi base_url i token oraz folderami już pogrupowanymi według domen poleceń.
GET /api/public/cli/openapi.json — Wersja bez uwierzytelnienia — suma trzech ról. Do projektowania i wyceny mostu, zanim masz token.
GET /api/public/cli/postman.json — Kolekcja Postman bez uwierzytelnienia: jeden plik, który możesz przekazać zespołowi.
Operacje: 761 — Polecenia: 721 + operacje REST i płaszczyzny sterowania: 36 + endpointy katalogu i tożsamości: 4. Liczby na tej stronie nie są wpisywane ręcznie; są liczone z bieżącego dokumentu przy każdym żądaniu, więc w dniu, w którym pojawi się nowe polecenie, rosną także tutaj — i sumują się.
Schemat zabezpieczeń — bearerAuth: token Passport wydany dla prawdziwego użytkownika. Klucz z zakresem odczytu może wywoływać tylko operacje oznaczone x-logistivo.read_only: true; próba zapisu zwraca 403 PRZED bramką potwierdzenia, więc klucz tylko do odczytu nigdy nie zobaczy 409.
Każda gałąź błędu jest rozpisana — Każda operacja opisuje osobno 401/403/404/409/422/429/500. Dwa znaczenia 409 (wymagane potwierdzenie / konflikt idempotencji) i dwa znaczenia 422 (błąd schematu / odrzucenie biznesowe) są w dokumencie rozróżnione, więc twój generator nie zlewa ich w jedną gałąź.
Bez znacznika czasu — Dokument nie zawiera czasu wygenerowania. Ten sam katalog daje te same bajty, dlatego ETag naprawdę działa, a definicja zapisana w systemie kontroli wersji nie wygląda na „zmienioną” po każdym pobraniu.
Nie wymyśliliśmy payloadów produktu — W endpointach zapisu REST opisane jest tylko pole kontraktowe (external_ref); reszta treści pozostaje otwarta jako additionalProperties: true, a czytelnik jest kierowany do dokumentacji produktu. Definicja niekompletna, ale prawdziwa, jest lepsza niż kompletna, ale wymyślona.
Lista kluczy błędów dla operacji NIE jest wyczerpująca — x-error-keys wymienia tylko klucze, które z pewnością wynikają z własnego rekordu polecenia, i mówi to przez x-error-keys-exhaustive: false. Pełny słownik jest w korzeniu dokumentu; każdy klucz, którego nie rozpoznajesz, traktuj jak ogólne niepowodzenie. Sfabrykowana „pełna lista” skłoniłaby cię do tego, by nigdy nie pisać gałęzi domyślnej.
Narzędzi wykrywania nie ma w definicji — search_commands, run_command i list_capabilities istnieją tylko wewnątrz pętli czatu i nie można ich wywołać przez HTTP. Gdyby zostały uwzględnione, twój generator napisałby trzy metody, które nigdy nie mogłyby działać.
Generowanie kodu: typowany klient z definicji
Masz definicję; teraz wygeneruj z niej działający kod. `lg codegen` czyta dokument OpenAPI i zapisuje jednoplikowego klienta bez zależności — TypeScript (deklaracje typów plus cienka nakładka wywołań) lub PHP (klasa klienta z kształtami tablic w PHPDoc). Bez `npm install`, bez composera: `fetch` po stronie TypeScript, `ext-curl` po stronie PHP.
Generowanie odbywa się na TWOIM komputerze, a nie na naszym serwerze. To nie kwestia preferencji: przypnij definicję w swoim repozytorium raz (`lg spec --out=...`), a to samo polecenie działa przy każdym buildzie bez sieci i bez tokenu, więc twoje CI nigdy nie zależy od dostępności naszych usług. A ponieważ wygenerowany kod to kod, który DZIAŁA w twoim ERP, trzymanie go w repozytorium zamiast pobierania z API sprawia, że każda zmiana jest widoczna w `git diff`.
Wygenerowany klient poprawnie obsługuje wszystkie trzy tory Logistivo i dowiaduje się, który jest który, z dokumentu, a nie przez zgadywanie: każda operacja deklaruje swój tor w `x-logistivo.surface`. Tor poleceń rozpakowuje kopertę `{success, data:{…}}`; lista synchronizacji REST NIE ma koperty i jest zwracana bez zmian (rozpakowanie usunęłoby `next_cursor`); zapis REST zwraca własną treść produktową endpointu. Generator ogólnego przeznaczenia nie zna tego rozróżnienia — nasz zna.
Typy nie są zgadywane: interfejs argumentów każdego polecenia jest generowany z tego samego JSON Schema, które widzi asystent. Wymagane pozostaje wymagane, enumy stają się typami unii, zagnieżdżone obiekty — zagnieżdżonymi typami. W praktyce: jeśli serwer wymaga pola, wywołanie, które o nim zapomni, nie zawiedzie z 422 na produkcji — zawiedzie podczas kompilacji.
Do pliku nie jest zapisywany znacznik czasu generowania: ta sama definicja z tymi samymi flagami daje te same bajty. Ponowne generowanie nie robi więc szumu w `git diff`, a jedyna rzecz, która naprawdę się zmieniła — kontrakt — pozostaje widoczna.
1. Przypnij definicję — Definicja jest generowana dla twojej roli; każdą operację w niej można wywołać tym tokenem. Zatwierdź plik w repozytorium (commit). lg login --api-key= lg spec --out=logistivo-openapi.json
2. Wygeneruj klienta — Powstaje jeden plik, zawierający jako metodę KAŻDĄ operację z przypiętej definicji: polecenia, które może wywołać twoja rola, endpointy REST niosące kontrakt integracyjny oraz endpointy wykrywania. Liczba dotyczy TWOJEJ roli, a nie całej platformy — dziś klucz nadawcy daje metody dla 646 poleceń, klucz przewoźnika — dla 621, klucz agencji celnej — dla 392. Generując z publicznej definicji bez uwierzytelnienia, dochodzisz do górnej granicy 761 operacji. 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. Sprawdź, potem używaj — Jeśli wygenerowany kod się nie kompiluje, wina leży po naszej stronie, a nie twojej: integralności definicji pilnuje wykonywalne sprawdzenie na serwerze. npx tsc --noEmit --strict --target ES2022 --module ESNext --moduleResolution bundler logistivo-client.ts php -l LogistivoClient.php
Jedna metoda na operację — Każde polecenie w dokumencie, każdy endpoint REST niosący kontrakt integracyjny i endpointy wykrywania. Generując z definicji twojej roli, dostajesz tylko to, co możesz wywołać (dla nadawcy — metody dla 646 poleceń); generując z definicji publicznej, dostajesz komplet 761 operacji. W dniu, w którym na serwerze zostanie dodane polecenie, ponowne wygenerowanie je uwzględni; nie trzeba czekać na wydanie klienta.
Typy argumentów — Schemat `args` każdego polecenia staje się interfejsem (w PHP — kształtem tablicy). Pola wymagane pozostają wymagane, enumy stają się uniami. W TypeScript zapomnienie wymaganego pola to błąd kompilacji; w PHP twoje IDE i PHPStan widzą ten sam kształt.
Klasy błędów — Taksonomia transportowa (`error_code`) i biznesowa (`error_key`) to osobne pola; bramka potwierdzenia i limit żądań to osobne typy błędów. Unia kluczy błędów pozostaje otwarta na nieznane wartości — gdy serwer zadeklaruje nowy klucz, twój kod nie przestaje się kompilować, tylko trafia do gałęzi `default`.
Poprawna polityka ponowień — Automatyczne ponowienia dotyczą tylko bezpiecznych wywołań: odczytów i zapisów z kluczem idempotencji. Zapis bez klucza, który przekroczy limit czasu, nie oznacza, że „nic nie zostało zapisane”, więc klient nigdy ślepo go nie powtarza. Przy 429 czeka tyle, ile wskazuje `Retry-After` serwera, zamiast wymyślać opóźnienie.
Treści wyników nie są typowane — Wyniki poleceń wracają jako `unknown` (`mixed` w PHP), z tego samego powodu co w samej definicji: kształty wyników to biznesowy wynik polecenia, a nie część kontraktu. Zgadnięty typ wyniku zacząłby kłamać przy pierwszym przesunięciu pola.
Wygenerowanego pliku nie edytuje się ręcznie — To wynik, a nie źródło. Jeśli potrzebujesz dodatkowego zachowania, opakuj wygenerowaną klasę; wszystko, co napiszesz w jej wnętrzu, przepadnie przy następnym generowaniu.
Narzędzia wykrywania nie są generowane — `search_commands`, `run_command` i `list_capabilities` żyją tylko wewnątrz pętli czatu i nie można ich wywołać przez HTTP; nie ma ich w definicji, a więc i w kliencie. Ich uwzględnienie oznaczałoby napisanie trzech metod, które nigdy nie działają.
Uczciwy zakres
Wolimy tę sekcję rozbudowywać niż skracać. Wartość kontraktu integracyjnego tkwi nie tyle w tym, co obiecuje, ile w tym, jak jasno mówi, czego nie obiecuje.
CLI działa w kontekście użytkownika tenanta — Każde polecenie działa w ramach firmy i roli użytkownika, którego token został przedstawiony. Tryb operatora platformy — tryb administracyjny, który czyta dane wielu firm — jest poza tą powierzchnią i nie zostanie stąd udostępniony.
Twoja lista poleceń zależy od twojej roli — Konto nadawcy ma dostęp do 646 poleceń, przewoźnika — do 621, agencji celnej — do 392, afilianta — do 55. Jeśli w twoim katalogu brakuje polecenia, najpierw sprawdź rolę; jeśli jest na liście, ale zostaje odrzucone, sprawdź zakres i poziom dostępu klucza. Konta kierowców w ogóle nie mają dostępu do tej powierzchni.
Niektóre polecenia zużywają kredyty — Zapytania taryfowe, generowanie dokumentów i kilka innych poleceń opartych na AI korzystają z salda kredytów twojego planu. Każdy wiersz katalogu zawiera credit_cost {mode, credits}: fixed to dokładna opłata za wywołanie, read_only nigdy nie pobiera opłaty, a computed oznacza, że opłata zależy od wywołania — credits ma wtedy wartość null, a rzeczywista kwota pojawia się na karcie potwierdzenia. Przebieg próbny (dry_run) mówi ci, ile kosztowałoby jedno wywołanie i czy twoje saldo to pokrywa.
Klucze integracyjne nie mogą sterować czatem w panelu — Asystent AI w panelu jest dla ludzi. Rozpoczęcie lub kontynuowanie sesji asystenta kluczem integracyjnym jest odrzucane z 403; agenci używają endpointów poleceń, lg lub kanału MCP, gdzie każde polecenie działa na poziomie dostępu klucza, a jego zapisy są rejestrowane jako zapisy integracyjne.
Katalog nie zastępuje istniejącego REST API — Powierzchnia REST, na której działają webowe i mobilne aplikacje Logistivo, pozostaje na miejscu i nadal podlega regule zgodności wstecznej. Katalog poleceń nie zastępuje CRUD-a zasobów; to warstwa CZASOWNIKÓW — jedyny, audytowany sposób wykonania danej czynności.
Polecenia listujące zwracają dziś małe okna — Dopóki polecenie listujące nie ogłosi cursor i updated_since w swoim schemacie, jego limit to 20 wierszy bez kursora. Nie jest ono przeznaczone do wyciągania pełnej kopii twoich danych; synchronizacja przyrostowa jest wdrażana polecenie po poleceniu.
Najczęściej zadawane pytania
Do czego służy Logistivo CLI?
Wykonuje pracę na twoim koncie Logistivo z terminala, ze skryptu lub z twojego własnego agenta AI: ładunki i kursy, zapytania transportowe, oferty i przetargi, flota, kierowcy i ich wydatki, dokumenty, kontakty i rozrachunki, faktury i księgowość, magazyn i stany magazynowe, członkowie zespołu, taryfy HS i cła antydumpingowe. Każda operacja zapisu w panelu ma swoje polecenie; płatności, zgody prawne i zamknięcie konta celowo pozostają w przeglądarce. Te same polecenia można wywołać przez HTTP w integracjach ERP/CRM oraz przez kanał MCP.
Jak nazywane są polecenia w Logistivo CLI?
Kształt to lg --parameter=value. Domena to encja w liczbie mnogiej (loads, demands, invoices, export-documents), a czasownik pochodzi z zamkniętego słownika, który rośnie tylko w wyniku świadomej decyzji (list, get, create, update, search, set-status, generate i tak dalej). Wszystkie czasowniki jednej encji mieszkają w jednej domenie, a para (domena, czasownik) jest unikalna w całym katalogu.
Jak uwierzytelnić się w CLI?
Interaktywnie lg login wyświetla kod zatwierdzenia, który potwierdzasz w przeglądarce po zalogowaniu się do Logistivo — do terminala nie wpisuje się ani hasła, ani klucza, a sesja pozostaje zalogowana i sama się odnawia, dopóki nie uruchomisz lg logout. lg login --password (e-mail i hasło) pozostaje jako rozwiązanie awaryjne. Na serwerach i w CI używaj klucza integracyjnego wydanego w panelu lub poleceniem lg keys create: lg login --api-key zapisuje go w lokalnym profilu, możesz też umieścić go w zmiennej środowiskowej LOGISTIVO_TOKEN. Przez HTTP token jest przesyłany w nagłówku Authorization: Bearer.
Czy mogę utworzyć konto serwisowe dla integracji z ERP?
Nie. Integracja łączy się tokenem prawdziwego użytkownika firmy utworzonego w panelu. Syntetyczna tożsamość bez firmy wyłącza izolację multi-tenant, czyni bezużyteczną kolumnę „kto to uruchomił” w rejestrze audytu i zostawia most, który nie milknie, gdy jego właściciel odchodzi. Właściwy wzorzec to dedykowany użytkownik z wąską rolą i konkretnym, wskazanym z nazwiska właścicielem.
Czy Logistivo ma środowisko testowe (sandbox)?
Tak, i jest ono samoobsługowe: dla twojej firmy otwierany jest osobny tenant sandbox — ten sam kod, ten sam katalog poleceń, własny rejestr kredytów. Środowisko wynika z firmy, do której należy klucz, i nie można go podać w żądaniu; wywołanie z niewłaściwym profilem zatrzymuje się po stronie serwera z 403 ENVIRONMENT_MISMATCH. Zapytanie transportowe otwarte w sandboxie nigdy nie trafia do prawdziwych przewoźników, zdarzenie z sandboxa nigdy nie jest dostarczane do twojej produkcyjnej subskrypcji webhooków, a twoje produkcyjne saldo się nie zmienia. Endpointy: POST /api/common/integration-sandbox (otwarcie), POST /api/common/integration-sandbox/keys (klucz), GET /api/common/integration-sandbox/go-live (lista kontrolna go-live). Po stronie lg flagi lg --sandbox i lg --live wybierają profil dla pojedynczego uruchomienia.
Jak odczytać wyjście lg --json w skrypcie?
Wyjście to cała koperta HTTP: { "success": bool, "data": { "contract_version", "command", "status", "result" }, "code", "message" }. Dane biznesowe (payload) znajdują się pod .data.result; w poleceniach listujących wiersze to .data.result., liczba to .data.result.count, a następna strona to .data.result.next_cursor. Poprawna ścieżka jq wygląda więc tak: lg loads list --json | jq -r '.data.result.loads[].load_code'. Ścieżka pomijająca kopertę nie zgłasza błędu, tylko po cichu zwraca null — w skrypcie typu watchdog staje się to alarmem, który nigdy nie przestaje się włączać. Jedynym wyjątkiem jest /api/public/status, którego treść celowo nie ma koperty.
Jeśli wyślę to samo żądanie dwa razy, czy powstaną zduplikowane rekordy?
Nie, jeśli wysłano idempotency_key. Drugie wywołanie z tym samym kluczem nie uruchamia polecenia ponownie; zwraca pierwszy wynik ze statusem replayed. Klucz powinien być UUID i musi pozostać TEN SAM przy kolejnych ponowieniach — generowanie nowego klucza dla każdej próby to to samo, co nieużywanie idempotencji.
Co robi --yes?
Przechodzi przez bramkę potwierdzenia. Gdy polecenie objęte bramką zostanie wywołane bez --yes, nic się nie zmienia: serwer w jednym zdaniu podsumowuje, co zamierza zrobić, mówi, czy jest to nieodwracalne, i się zatrzymuje (HTTP 409, kod wyjścia CLI 4). Powtórzenie polecenia z --yes wykonuje pracę.
Jak wykryć w skrypcie nieudane polecenie?
Czytaj kod wyjścia, nigdy tekst komunikatu: 0 sukces, 1 odrzucenie przez regułę biznesową, 2 błąd polecenia lub argumentu, 3 błąd uwierzytelnienia lub roli, 4 wymagane potwierdzenie. Przez HTTP odpowiednikami są 200, 422, 404, 403 i 409, a pole error_code w treści jest stabilne. KOMUNIKAT błędu jest zlokalizowany i zmienia się bez uprzedzenia.
Jak programowo odkryć dostępne polecenia?
GET /api/public/cli/catalog do wykrywania bez uwierzytelnienia oraz GET /api/common/commands dla listy, którą twoje konto faktycznie widzi. Oba zwracają parametry JSON Schema każdego polecenia; buduj klienta na ich podstawie, zamiast kodować listę poleceń na sztywno.
Czy muszę aktualizować klienta, gdy dodawane jest nowe polecenie?
Nie. Klient pobiera listę poleceń z katalogu, więc polecenie dodane na serwerze pojawia się bez nowego wydania klienta. Aktualizacja jest potrzebna tylko przy zmianie łamiącej zgodność, która podnosi wersję kontraktu, a wtedy stary kształt pozostaje aktywny przez co najmniej sześć miesięcy.
Czy CLI zastępuje istniejące REST API?
Nie. Powierzchnia REST, na której działają aplikacje webowe i mobilne, pozostaje na miejscu. Katalog poleceń nie zastępuje CRUD-a zasobów; to warstwa czasowników — jedyny sposób wykonania działania, objęty bramką ról, bramką potwierdzenia i audytem.
Jak uzyskać klucz API Logistivo i co może on robić?
Menedżer z uprawnieniem do zarządzania zespołem wydaje go w panelu w Settings › Integration keys albo z terminala poleceniem lg keys create. Klucz działa w imieniu prawdziwego członka zespołu i ma trzy niezależne ustawienia: zakres (read otwiera katalog i polecenia niezapisujące, write otwiera każde polecenie — bramka potwierdzenia pozostaje bez zmian), opcjonalne uprawnienia domenowe oraz poziom dostępu — employee, domyślny, do codziennych operacji, lub manager do spraw zespołu, ustawień, kluczy i pieniędzy. Jest pokazywany raz i nie jest przechowywany na serwerze; można go rotować, przenosić i unieważniać. Gdy członek, w imieniu którego działa, odchodzi, klucz również zostaje zamknięty. Nie ma konta serwisowego.
Co się stanie, jeśli użyję klucza idempotencji ponownie z innym poleceniem?
Serwer odpowiada 409 idempotency_conflict i podaje polecenie, z którym klucz został użyty po raz pierwszy; nic się nie wykonuje i nic nie jest odtwarzane. Klucze są ograniczone do twojej firmy, powiązane z jednym poleceniem i zablokowane na 24 godziny — potem ten sam klucz rozpoczyna nowe wykonanie.
Jak limity żądań są stosowane do mojej integracji?
Per token, na minutę, w trzech pulach: odczyty katalogu 120, polecenia odczytu 120, polecenia zapisujące 30. 429 zawsze zawiera Retry-After oraz treść z retry_after, limit i bucket; odczekaj tyle i ponów. Katalog publikuje aktualne wartości pod rate_limits.
Jak odróżnić odrzucenie biznesowe od błędu transportowego?
Najpierw opieraj rozgałęzienia na error_code: failed (422) to odrzucenie biznesowe i niesie stabilny error_key, taki jak INSUFFICIENT_CREDITS lub NOT_FOUND; server_error (5xx) i błędy sieci ponawiasz z tym samym kluczem idempotencji; przy rate_limited (429) odczekujesz. Nigdy nie opieraj rozgałęzień na tekście błędu.
Czy Logistivo wysyła webhooki? Dla jakich zdarzeń?
Tak. Rejestrujesz adres https i wybierasz zdarzenia, które cię interesują; gdy się wydarzą, przychodzi podpisany POST. Liczba zdarzeń, które można dziś subskrybować: 13 — ładunek: utworzenie/zmiana statusu/przypisanie kierowcy; zapytanie transportowe: utworzenie i zmiana statusu; oferta: złożenie/korekta/akceptacja; faktura: szkic/wystawienie/anulowanie; rezerwacja magazynowa: utworzenie/zmiana statusu. Za każdą nazwą stoi klasa zdarzenia, która jest faktycznie wysyłana — nic nie jest ogłaszane, by potem nigdy nie zostać wywołane, bo takie zdarzenie to cicha awaria, na którą integrator czeka w nieskończoność. Subskrypcje tworzy się w Settings › Integration › Webhooks albo z terminala poleceniem lg webhooks create.
Jak zweryfikować podpis webhooka Logistivo?
Każde żądanie zawiera nagłówek X-Logistivo-Signature: t=,v1=. Podpisywany ciąg to ".", algorytm to HMAC-SHA256, a kluczem jest sekret subskrypcji. Cztery zasady: (1) weryfikuj SUROWE bajty — dekodowanie i ponowna serializacja treści (JSON.stringify / json_encode) zamienia te same dane w inne bajty i podpis przestaje się zgadzać; to najczęstszy błąd; (2) sprawdzaj znacznik czasu i odrzucaj wszystko, dla czego |now − t| > 300 s, nawet jeśli podpis jest poprawny; (3) porównuj w stałym czasie za pomocą hash_equals / timingSafeEqual; (4) deduplikuj po event_id, a nie po id dostarczenia — event_id jest zachowywany przy ponownym wysłaniu, a id dostarczenia się zmienia. Działające odbiorniki w Node i PHP znajdują się w repozytorium w examples/webhook-receiver/ i testują się same przez --selftest.
Co się stanie, jeśli webhooka nie da się dostarczyć? Czy stracę zdarzenie?
Nie. Jeśli twój odbiornik nie zwróci 2xx, dostarczenie trafia do harmonogramu ponowień: 60 · 300 · 1800 · 7200 · 21600 s, łączna liczba prób: 6, okno około 8,6 h. KAŻDA awaria poza 410 Gone jest ponawiana, łącznie z 4xx — utrata zdarzenia biznesowego kosztuje więcej niż kilka dodatkowych żądań. Po 10 kolejnych dostarczeniach, które wyczerpały ponowienia, subskrypcja jest wyciszana, a powód zapisywany, więc na pytanie „dlaczego nic nie przychodzi” wciąż da się odpowiedzieć. Rejestr dostarczeń przechowuje każdą próbę (kod statusu, czas trwania, błąd), a pojedyncze dostarczenie możesz wysłać ponownie z panelu lub poleceniem lg webhooks replay. Synchronizacja przyrostowa (updated_since + cursor) nadal pozostaje siatką bezpieczeństwa.
Czy mój agent AI może zrobić wszystko, co użytkownik może zrobić w panelu?
Prawie wszystko. Każda operacja zapisu w panelu ma swoje polecenie — w pomiarze względem endpointów zapisu panelu pokrytych jest 100% endpointów objętych zakresem — a te same polecenia są dostępne z lg, przez HTTP i przez kanał MCP. Celowe wyjątki to kroki dotyczące tożsamości i pieniędzy: logowanie, zakup pakietu, dodanie karty z 3D Secure, akceptacja tekstów prawnych i zamknięcie konta pozostają w przeglądarce danej osoby, a lg handoff-links generate zwraca dla nich link. Kluczami integracyjnymi, webhookami i sandboxem zarządza się wbudowanymi poleceniami lg, bo zwracają one sekrety jednorazowo.
Czy mogę przekazywać do poleceń pliki, takie jak PDF-y lub zdjęcia, z CLI lub API?
Tak. W lg poprzedź ścieżkę lokalną znakiem @ (--attachment_uuid=@./cmr.pdf), a lg najpierw prześle plik; --file to skrót, gdy polecenie ma jedno pole plikowe, a lg upload tylko przesyła plik. Przez HTTP wyślij plik jako multipart do POST /api/common/commands:upload i przekaż zwrócony attachment_uuid poleceniu; klienci MCP używają narzędzia upload_attachment. Typ jest rozpoznawany na podstawie zawartości, przesłane pliki należą do użytkownika i pozostają użyteczne przez 24 h, a ponowne przesłanie tego samego pliku zwraca ten sam identyfikator.
Czym różni się klucz integracyjny employee od klucza manager?
Poziom dostępu decyduje o tym, jak poważną pracę może wykonywać klucz. Klucz employee, domyślny dla nowych kluczy, wykonuje codzienne operacje: ładunki, zapytania transportowe, oferty, kursy, flota, dokumenty i kontakty. Klucz manager może też wykonywać prace zarządcze — członkowie zespołu i role, ustawienia firmy, klucze integracyjne, konta bankowe, zapisane karty, wypłaty dla afiliantów. Klucz nigdy nie ma większych uprawnień niż osoba, w imieniu której działa, a klucz employee wywołujący polecenie na poziomie manager dostaje INSUFFICIENT_KEY_LEVEL. Poziom zmienisz w panelu lub poleceniem lg keys update --access-level=manager.
Czy afiliant (partner polecający) może korzystać z CLI?
Tak. Konto afilianta dostaje własny katalog z 55 poleceniami — dla rekomendacji (referrals), leadów, notatek i zadań CRM, prezentacji sprzedażowych, zarobków i wypłat — i korzysta z niego przez lg, HTTP lub MCP jak każda inna rola. Zlecenie lub anulowanie wypłaty oraz zmiana konta bankowego do wypłat wymagają klucza na poziomie manager i potwierdzenia. Firma, która jest też nadawcą, przewoźnikiem lub agencją celną, widzi oba katalogi.
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.