Logistivo CLI: conduceți operațiunile logistice din terminal și din ERP-ul dumneavoastră
Un singur catalog de comenzi alimentează trei interfețe: clientul de terminal lg, asistentul AI din panoul de control și canalul la care se conectează asistenții AI externi. O capabilitate se scrie o singură dată și apare în toate trei — iar acum fiecare acțiune de scriere din panou are o comandă, astfel încât scripturile și propriii dumneavoastră agenți AI pot face munca pe care echipa o face pe ecran. Plățile, consimțământul legal și închiderea contului rămân în mod deliberat în browser. Această pagină este un contract. Tabelul de comenzi de mai jos nu este scris de mână; este generat la fiecare cerere din registrul live de comenzi.
Ce este Logistivo CLI?
Logistivo CLI (lg) este un client de linie de comandă care execută munca din contul dumneavoastră Logistivo — încărcături și curse, cereri de transport, oferte și licitații, flotă și șoferi, documente, contacte și conturi curente, facturi și contabilitate, depozit și stoc, membri ai echipei și tarife vamale — dintr-un terminal, dintr-un script sau din propriul dumneavoastră agent AI. Comenzile nu sunt încorporate în client: clientul preia catalogul de comenzi de pe server și se construiește pe baza lui. Aceleași comenzi pot fi apelate prin HTTP fără a instala nimic — aceasta este calea folosită de integrările ERP și CRM — precum și prin canalul MCP la care se conectează asistenții AI externi.
O singură formă de comandă: lg --parameter=value. Catalogul conține astăzi 721 de comenzi în 175 de domenii; cea mai largă listă pe care o vede un singur rol are 646 de comenzi în 165 de domenii.
Fiecare acțiune de scriere din panou are o comandă — măsurat față de endpoint-urile de scriere ale panoului, 100% dintre cele aflate în perimetru sunt acoperite. Plățile (3D Secure), consimțământul legal și închiderea contului rămân în mod deliberat în browser; pentru acestea, o comandă returnează în schimb un link.
Comenzile care primesc un document sau o fotografie funcționează și în afara browserului: scrieți --attachment_uuid=@./cmr.pdf, iar lg încarcă mai întâi fișierul; prin HTTP încărcați fișierul la /api/common/commands:upload și transmiteți attachment_uuid returnat.
Cheile de integrare au un nivel de acces: employee (implicit pentru cheile noi) pentru operațiunile de zi cu zi, manager pentru echipă, setări, chei și bani. O cheie nu are niciodată mai multe drepturi decât persoana în numele căreia acționează.
Flag-urile nu sunt niciodată inventate: fiecare flag este un nume de parametru din propria JSON Schema a comenzii, de unde provin și tipul său și faptul că este sau nu obligatoriu.
Comenzile de scriere cer confirmare; cele ireversibile nu rulează niciodată fără ea (HTTP 409, cod de ieșire CLI 4).
Reîncercarea nu creează duplicate: un apel care poartă un idempotency_key rulează cel mult o dată.
Fiecare execuție ajunge într-un singur registru de audit — se consemnează dacă a venit dintr-un terminal, din chat sau de la un asistent.
Ce este live astăzi și ce urmează
Această secțiune se află intenționat în partea de sus a paginii. Cea mai costisitoare greșeală pe care o poate face un document de integrare este să descrie un endpoint care nu este încă deschis ca și cum ar fi: integratorul scrie codul, endpoint-ul returnează 404, iar încrederea nu se mai întoarce.
Deoarece contractul este înghețat, codul de integrare pe care îl scrieți astăzi continuă să funcționeze pe măsură ce restul pieselor se deschid. Câmpurile pe care nu le cunoașteți trebuie ignorate; această regulă ne permite să adăugăm fără a strica nimic.
Catalogul de comenzi și tabelul de identitate — Identitatea publică domeniu/verb a fiecărei comenzi este înghețată, iar versiunea contractului este publicată ca 1 în fiecare răspuns al catalogului și în antetul X-Contract-Version. Tabelul de pe această pagină este generat din registrul live: o comandă adăugată pe server apare aici de la sine, iar o comandă eliminată dispare.
Endpoint de descoperire fără autentificare — GET /api/public/cli/catalog — numele comenzilor, identitatea domeniu/verb, descrierea, parametrii JSON Schema, flag-urile de poartă și câmpurile de versionare (since, deprecated_at, replaced_by, aliases). Fără autentificare: emiterea unui token este un pas care vine DUPĂ decizia de integrare, nu înaintea ei. Răspunsul nu conține deloc date ale vreunui tenant.
Endpoint-uri autentificate de catalog și de execuție — GET /api/common/commands, GET /api/common/commands/{name} și POST /api/common/commands/{name}. Poarta de rol, poarta de confirmare, idempotența și registrul de audit se află într-un singur punct de aplicare, prin care trec și chatul și terminalul.
Acoperirea panoului: fiecare acțiune de scriere are o comandă — 721 de comenzi în 175 de domenii, verificate față de endpoint-urile de scriere ale panoului: fiecare endpoint din perimetru este acoperit de o comandă (o oglindă a endpoint-ului sau același serviciu partajat) și niciunul nu rămâne nedovedit. În mod deliberat în afara perimetrului: plățile cu 3D Secure, consimțământul legal, închiderea contului și autentificarea, care rămân în browser; gestionarea cheilor, a webhook-urilor și a sandbox-ului, care sunt comenzi încorporate în lg; și endpoint-urile proprii ale aplicației pentru șoferi.
Preflight (dry_run): vedeți efectul fără a rula comanda — Cu dry_run: true în corpul cererii, comanda nu rulează: validarea, poarta de rol/scope, rezolvarea țintelor și calculul creditelor se execută toate și se întoarce o previzualizare; nu se scrie nimic, nu se consumă credit, iar cheia de idempotență nu este consumată. Îl acceptă și endpoint-ul batch, per lot. Un preflight nu intră niciodată în handler-ul comenzii; la lansare, 178 de preflight-uri pe toate comenzile de scriere existente atunci în catalog nu au produs nicio instrucțiune de scriere.
Chei de integrare — Chei API care acționează în numele unui membru real al echipei, emise în panou sau cu lg keys create: scope de citire/scriere, un nivel de acces (employee implicit, sau manager), durată de viață, ultima utilizare, rotire, transfer și revocare. lg login --api-key, lg whoami și un lg logout care revocă cheia și pe server sunt construite pe ele.
Sandbox — exersați scrierile fără a atinge producția — Un tenant sandbox separat pentru fiecare companie, cu același catalog de comenzi; se deschide în regim self-service și își emite propria cheie. Creditele, marketplace-ul și rutarea webhook-urilor sunt separate între cele două medii; mediul este dedus din compania cheii și nu poate fi transmis odată cu cererea.
Versionare, taxonomia erorilor, idempotență și limite de rată — Comenzile poartă since / deprecated_at / replaced_by / aliases, iar o comandă depreciată răspunde cu un antet X-Deprecated. Eșecurile de business poartă un error_key stabil alături de error_code de nivel de transport, iar dicționarul cheilor este publicat în catalog. Cheile de idempotență sunt limitate la compania dumneavoastră, legate de o singură comandă și blocate timp de 24 de ore. Limitele de rată (rate limits) sunt per token, în trei categorii, iar fiecare 429 poartă Retry-After.
Webhook-uri de ieșire: un POST atunci când se întâmplă ceva — Notificarea push semnată este live pentru 13 evenimente. Abonamentele se gestionează din panou sau cu lg webhooks; semnătura își poartă propriul timestamp, programul de reîncercări, în secunde, este 60 · 300 · 1800 · 7200 · 21600, iar motivul dezactivării este întotdeauna înregistrat. Fiecare nume de eveniment este susținut de o clasă de eveniment care este efectiv emisă — nimic nu este anunțat și apoi niciodată trimis. Calea pull (updated_since + cursor) nu a fost eliminată: push-ul a fost adăugat lângă ea, nu în locul ei.
Comenzi care primesc fișiere — 38 de comenzi primesc un document sau o fotografie — un CMR, o factură, un certificat de înmatriculare, fotografii de paleți. Încărcați o singură dată la POST /api/common/commands:upload, sau lăsați lg să o facă cu --attachment_uuid=@./file.pdf, și transmiteți attachment_uuid returnat; clienții MCP folosesc instrumentul upload_attachment. Tipul fișierului este detectat din conținut, iar o încărcare rămâne utilizabilă 24 de ore.
Clientul de terminal lg — Publicat pe npm sub licența MIT: instalați cu `npm install -g @lgstv/lg` sau rulați-l fără instalare prin `npx @lgstv/lg`. Este un singur fișier fără dependențe și, deoarece interfața HTTP este deschisă, vă puteți integra și fără el. Se autentifică printr-un cod de aprobare pe care îl confirmați în browser și apoi rămâne autentificat, reînnoindu-și singur sesiunea; încarcă fișierele locale în locul dumneavoastră (@path, --file, lg upload), gestionează cheile de integrare (lg keys), nu primește niciodată un secret în linia de comandă, respectă Retry-After, reîncearcă erorile 5xx cu aceeași cheie de idempotență și avertizează la comenzile depreciate și la versiunile mai noi ale contractului.
Sincronizare incrementală: paginare cu cursor și updated_since — Contractul de mai jos (limit + cursor opac semnat, next_cursor, updated_since) este fix și este implementat treptat pe comenzile de listare. Până când o anumită comandă de listare nu declară cursor și updated_since în JSON Schema sa, tratați-o ca pe o fereastră mică: plafon de 20 de rânduri, fără cursor.
Ce face diferența: clientul nu cunoaște nicio comandă, ci le extrage
Aceasta este singura decizie care dă sens restului paginii. Într-un CLI obișnuit, comenzile trăiesc în interiorul clientului; în Logistivo ele trăiesc pe server.
În aranjamentul clasic, când serverul capătă o capabilitate, clientul are nevoie de o versiune nouă, iar utilizatorul trebuie să o instaleze. Între timp, cele două părți știu lucruri diferite — și acesta este cel mai discret mod de eșec al integrărilor: scriptul rulează, codul de ieșire este 0, iar comanda pur și simplu nu descrie ceea ce poate face serverul.
În Logistivo, definiția unei comenzi este o singură înregistrare: numele ei, ce face, parametrii JSON Schema, ce roluri o pot vedea, dacă are nevoie de confirmare și dacă efectul ei este reversibil. Când lg pornește, preia acest catalog și generează din el textul de ajutor, flag-urile și validarea intrărilor. În momentul în care o comandă este adăugată pe server, lg o cunoaște — fără nicio actualizare a clientului.
Același catalog alimentează asistentul AI din panoul de control și canalul la care se conectează asistenții AI externi. O capabilitate se scrie o singură dată și apare în trei locuri — iar toate trei trec prin aceeași poartă de rol, aceeași poartă de confirmare și același registru de audit. Nu există un inventar separat de comenzi CLI; dacă ar exista, cele trei interfețe s-ar despărți pe nesimțite în șase luni.
Nicio divergență de versiuni — Lista de comenzi pe care o cunoaște clientul este, prin construcție, lista pe care o are serverul. Întrebarea „Ce versiune de lg are această comandă?” pur și simplu nu există.
Numele flag-urilor nu se ghicesc niciodată — Flag-urile unei comenzi sunt exact numele parametrilor din JSON Schema sa. Ca să aflați ce acceptă o comandă, nu citiți un document, ci catalogul — iar catalogul este mereu actual.
CLI-ul dumneavoastră este cât contul dumneavoastră — Catalogul este filtrat pe rol: o comandă pe care rolul dumneavoastră nu o poate vedea nu apare niciodată în listă. Un cont de transportator vede 621 de comenzi, un expeditor 646, un comisionar vamal 392, iar un cont de afiliat (partener de recomandare) are un set propriu: 55 de comenzi.
Documentația nu poate rămâne în urmă — Tabelul de comenzi de pe această pagină provine din același registru. Nu există nicăieri o listă pe care un om să trebuiască să o țină sincronizată cu realitatea.
Regula de denumire — cum cresc numele comenzilor
Catalogul va crește. Comenzile noi nu sunt denumite ad-hoc; se aplică șase reguli. Le publicăm aici pentru că acestea sunt numele pe care integrarea dumneavoastră le va scrie ani de zile, iar predictibilitatea lor are valoare pentru dumneavoastră.
Un domeniu este o entitate la plural — loads, demands, invoices, export-documents. Domeniile din două cuvinte sunt în kebab-case. Singura excepție este un substantiv nenumărabil: stock nu se pune niciodată la plural, pentru că „stocks” înseamnă altceva.
Toate verbele unei entități stau într-un singur domeniu — loads conține fiecare verb care acționează asupra unei încărcături: create, list, get, update, set-status, assign-driver, list-problems, archive și altele. Deschiderea unui domeniu nou pentru fiecare verb (load-statuses, load-drivers) l-ar obliga pe utilizator să caute aceeași entitate în trei locuri.
Verbul nu se scurge niciodată în domeniu; domeniul este ceea ce SE SCHIMBĂ — Alocarea unui șofer modifică încărcătura, nu șoferul, deci comanda este lg loads assign-driver. Complementul indirect (-driver) se atașează verbului, niciodată domeniului.
O sub-resursă nu primește niciodată propriul domeniu — O linie de factură și un articol de document nu pot fi listate separat; ele sunt adresate prin proprietarul lor — lg invoices add-line, lg export-documents add-item. Un singur test decide: dacă nu puteți lista sau obține lucrul respectiv independent, nu este un domeniu.
Restrângerea este un flag, nu un verb nou — lg fleet-documents list --days=30 este corect; nu există un verb separat „list-expiring”, pentru că fereastra este deja un parametru. Un verb calificat se folosește doar atunci când rândurile returnate nu sunt entitatea domeniului: loads list-problems returnează semnalări de probleme, nu încărcături.
Perechea (domeniu, verb) este unică în întregul catalog — Chiar și pentru două comenzi ale căror roluri nu se suprapun niciodată. Dacă aceeași pereche ar fi dată la două comenzi, codul de integrare s-ar uita la un singur nume, în timp ce CLI-ul ar rula lucruri diferite în funcție de cine l-a apelat.
Acoperire: tot ce este în panou, printr-o comandă
Multe echipe conectează Logistivo la propriul agent AI sau la propriul sistem de automatizare, iar un agent este util doar dacă poate duce treaba la capăt. Așa că regula este simplă: orice poate modifica un utilizator de birou în panou, poate modifica și o comandă — în spatele aceleiași porți de rol, aceleiași porți de confirmare și aceluiași registru de audit.
Acest lucru este măsurat, nu afirmat. Fiecare endpoint de scriere din spatele panoului este verificat față de registrul de comenzi, iar un endpoint se consideră acoperit doar atunci când o comandă îl declară drept oglinda sa HTTP sau apelează același serviciu partajat. Dintre endpoint-urile de scriere aflate în perimetru, 100% sunt acoperite și niciunul nu rămâne nedovedit. Fiecare endpoint lăsat deoparte are un motiv scris — pași de identitate și de plată, planul de control al integrării, endpoint-urile proprii ale aplicației pentru șoferi, telemetria clientului, copii moarte fără apelant — iar cele care contează pentru un integrator sunt listate mai jos.
Comenzile care primesc un fișier se supun aceleiași reguli: 38 de comenzi din tabel primesc un document sau o fotografie și toate funcționează din lg, prin HTTP și prin MCP (vedeți Comenzi care primesc fișiere).
Și munca de management este acoperită, în spatele unei chei mai puternice: 87 de comenzi din tabel — membri ai echipei și roluri, setările companiei, conturi bancare, carduri salvate, chei de integrare — necesită o cheie de integrare de nivel manager. O cheie de nivel employee, cea implicită, rulează operațiunile de zi cu zi și este refuzată pentru acestea cu INSUFFICIENT_KEY_LEVEL.
Conturile de afiliat (partener de recomandare) au un catalog propriu: 55 de comenzi în 20 domenii — recomandări, lead-uri, note și sarcini CRM, prezentări de vânzare, câștiguri și plăți, plus comenzile de cont și de echipă pe care le are fiecare rol. Comenzile exclusive afiliaților nu se află în tabelul public de mai jos, care listează cele trei roluri ale panoului; un cont de afiliat le vede în GET /api/common/commands și în lg commands. O companie care este atât afiliat, cât și expeditor, transportator sau comisionar vamal vede ambele seturi.
Un agent ar trebui să înceapă cu lg users get (nume API get_current_user): returnează rolul, nivelul de acces al cheii folosite, permisiunile efective și dacă o aprobare legală în așteptare sau un număr de telefon neverificat blochează în acest moment scrierile — astfel încât agentul să poată anticipa un refuz în loc să-l colecționeze.
Acoperirea este măsurată printr-un raport care compară registrul de comenzi cu endpoint-urile de scriere ale panoului; un endpoint de panou adăugat fără o comandă apare în acest raport ca nedovedit. Dacă găsiți o acțiune din panou pe care nu o puteți atinge printr-o comandă, raportați-o suportului.
1. Cereți linkul — Munca ce trebuie să aibă loc în sesiunea de browser proprie a persoanei nu este o comandă, dar suprafața de comenzi știe de ea. lg handoff-links generate (nume API get_browser_handoff_link) returnează un link logistivo.com pentru scopurile pe care le permite rolul dumneavoastră: package_purchase, payment_cards, legal_documents, integration_keys, affiliate_demo_accounts și account_close. Este gratuit, nu scrie nimic, iar linkul nu poartă niciun secret — persoana se autentifică în mod obișnuit.
2. Predați-l persoanei — Arătați linkul utilizatorului sau trimiteți-l prin propriul dumneavoastră canal. Persoana finalizează pasul acolo: aprobarea contractului și plata 3D Secure pentru un pachet, adăugarea unui card, aprobarea textelor legale în așteptare, emiterea unei chei API al cărei secret este afișat o singură dată sau închiderea propriului cont.
3. Citiți rezultatul cu o comandă — Odată ce pasul este finalizat, rezultatul său este din nou vizibil pentru comenzi: pachetul și soldul de credite, cardul salvat (mascat, doar ultimele patru cifre), cheia nouă în lista de chei. Un agent nu primește niciodată într-un chat un număr de card, o plată sau un consimțământ.
Plăți și 3D Secure — Cumpărarea sau upgrade-ul unui pachet și adăugarea unui card necesită 3D Secure în browser. Comenzile listează pachetele și prețurile, citesc soldul și istoricul acestuia, listează cardurile salvate (mascate), setează cardul implicit și elimină un card; cumpărarea propriu-zisă trece prin linkul de predare.
Consimțământ legal — Aprobarea textelor legale o face persoana, în browser. lg users get vă spune că o aprobare este în așteptare; nicio comandă nu o poate da.
Închiderea contului, autentificarea și parola — Închiderea propriului cont, autentificarea și schimbarea parolei sunt pași de identitate și rămân în browser. lg user-accounts preview arată ce ar însemna închiderea contului, fără a o efectua.
Chei de integrare, webhook-uri și sandbox — Gestionarea lor returnează secrete care trebuie afișate o singură dată, în terminalul dumneavoastră, de aceea sunt comenzi încorporate în lg (lg keys, lg webhooks, lg sandbox) peste propriile endpoint-uri HTTP, nu comenzi de catalog. Catalogul conține doar cele două comenzi de chei fără secrete: integration-keys list și integration-keys revoke.
Chatul asistentului din panoul de control — Cheile de integrare nu pot conduce chatul asistentului AI din panoul de control; pornirea sau continuarea unei rulări cu o cheie răspunde cu 403. Un agent se conectează în schimb prin endpoint-urile de comenzi, lg sau canalul MCP — acolo fiecare comandă rulează la nivelul de acces al cheii, iar scrierile ei sunt înregistrate ca scrieri de integrare.
Aplicația pentru șoferi — Conturile de șofer nu au catalog de comenzi, iar aplicația pentru șoferi își păstrează propriile endpoint-uri. Utilizatorii de birou gestionează șoferii, documentele, cheltuielile și cursele lor prin comenzi.
Instalare și identitate
lg este un script Node într-un singur fișier, fără dependențe (Node 18+), publicat pe npm ca @lgstv/lg. Pachetul instalează două comenzi identice, lg și logistivo — folosiți logistivo dacă lg este deja un alias pe mașina dumneavoastră. Fiind un singur fișier, funcționează și copierea lui lg.mjs pe serverul ERP al unui client. Nu aveți nevoie de client pentru a construi o integrare ERP/CRM — aceleași comenzi sunt disponibile prin HTTP.
1. Instalare — Aveți nevoie doar de Node 18 sau mai nou; nu există alte dependențe. Instalați-l global sau rulați-l fără instalare prin npx.
2. Autentificare cu un cod de aprobare — lg login afișează un cod de aprobare scurt și deschide logistivo.com/connect în browser; prin SSH, în CI sau cu --no-browser doar afișează adresa, pe care o puteți deschide pe orice dispozitiv, inclusiv pe telefon. Autentificați-vă acolo ca de obicei, verificați că codul de pe pagină este același cu cel din terminal, alegeți accesul doar de citire sau de citire și acțiune și aprobați. În terminal nu se tastează nimic secret: nicio parolă, nicio cheie, niciun cod de unică folosință. Sesiunea rămâne apoi autentificată pe acel computer — închiderea terminalului nu vă deconectează, iar lg reînnoiește singur token-ul de acces înainte să expire. lg logout închide sesiunea și pe server, iar o puteți elimina și din panou, la Settings › Integration keys › AI and CLI connections (Setări › Chei de integrare › Conexiuni AI și CLI). lg login --password (e-mail și parolă) rămâne ca variantă de rezervă. Necesită lg 0.11 sau o versiune mai nouă.
3. Pentru servere și CI: o cheie, nu un cod de aprobare — Pe un server sau într-un job de CI nu există nimeni care să aprobe un cod în browser. Emiteți o cheie în panou (Settings › Integration keys, adică Setări › Chei de integrare) sau cu lg keys create — opțional în numele unui membru al echipei dedicat, cu drepturi restrânse — și puneți-o în LOGISTIVO_TOKEN, sau salvați-o cu lg login --api-key. Cât timp variabila este setată, fișierul de configurare nu este citit niciodată. Detalii: secțiunea „Conectarea cu o cheie API”.
4. Verificați și explorați catalogul — lg commands listează fiecare comandă pe care o poate vedea rolul dumneavoastră, grupată pe domenii; lg help afișează verbele acelui domeniu, iar lg help afișează lista completă de parametri ai unei comenzi, cu tipurile lor și cu cei obligatorii. Niciunul dintre aceste texte nu trăiește în client — toate vin din catalog. Rețineți că lista depinde de rolul dumneavoastră: verbele unui domeniu nu sunt aceleași pentru un transportator și pentru un expeditor (loads set-status, de exemplu, există doar în catalogul transportatorului). Dacă lipsește un verb, verificați-vă rolul înainte de a verifica instalarea.
Nu puneți niciodată cheia în sistemul de control al versiunilor, într-un log de CI sau într-o fereastră de chat. Dacă v-ați autentificat cu un cod de aprobare sau cu o cheie de integrare, lg logout închide accesul și pe server; într-o sesiune cu parolă (lg login --password) șterge doar copia LOCALĂ și spune acest lucru explicit. Registrul de audit stochează argumentele dumneavoastră, dar maschează ca *** orice câmp al cărui nume conține token, password, IBAN, card sau OTP, precum și fiecare parametru pe care o comandă îl declară secret.
LOGISTIVO_TOKEN — Token de acces personal. Cât timp este setat, fișierul de configurare nu este citit niciodată — aceasta este calea preferată în CI și pe servere.
LOGISTIVO_BASE_URL — Rădăcina serverului. Implicit https://logistivo.com. Schimbați-o doar dacă indicați spre propriul dumneavoastră mediu; flag-ul --base-url face același lucru pentru o singură comandă.
LOGISTIVO_HOME — Directorul pentru fișierul de configurare și pentru cache-ul catalogului. Implicit ~/.logistivo. Separați-l dacă lucrați cu două conturi pe aceeași mașină.
LOGISTIVO_PROFILE — Profilul cu care se rulează. `lg profile use` este alegerea persistentă; această variabilă este pentru o singură rulare și este cel mai scurt mod de a comuta între un profil live și unul sandbox în CI. Un nume de profil necunoscut nu este ignorat în tăcere — produce o eroare.
NO_COLOR — Când este setată, nu se afișează nicio culoare ANSI (forma permanentă a flag-ului `--no-color`). Activați-o pentru un bridge care scrie într-un fișier de log sau în output-ul CI; secvențele escape de culoare strică instrumentele care citesc ulterior acele loguri.
Ergonomia clientului
Aceste funcționalități ușurează utilizarea de zi cu zi a clientului `lg`. Niciuna nu schimbă contractul HTTP — săriți peste această secțiune dacă vă integrați direct prin HTTP.
Medii și chei multiple — Țineți staging-ul și producția, sau bridge-urile pentru client și pentru transportator, în profiluri separate. Lista de profiluri nu afișează niciodată un token; fiecare rând arată amprenta sha256 a token-ului. Catalogul de comenzi este păstrat în cache per profil, gazdă și token, astfel încât două roluri nu pot vedea niciodată una lista de comenzi a celeilalte.
Sincronizare incrementală: lg sync — Rulează bucla de sincronizare din ghidul practic într-o singură comandă: un watermark per entitate, updated_since cu un cursor, output JSONL și o marjă de siguranță de cinci minute. Folosiți --full pentru prima umplere inițială (backfill). Comanda este doar de citire; nu există flag-ul --write. lg sync --list deduce din catalog entitățile sincronizabile pentru rolul dumneavoastră.
Experiența erorilor și completarea în shell — La 422, clientul numește câmpul respins sub forma flag-ului pe care l-ați tastat, împreună cu error_key stabil și explicația acestuia din catalog. La 409 afișează linia de comandă gata pregătită cu --yes; la 429 așteaptă cât indică Retry-After. Completarea în shell acoperă domeniile, verbele, flag-urile și valorile enum și funcționează offline.
Parametrii secreți nu ajung niciodată în linia de comandă — Câteva comenzi primesc un secret — conectarea integrării contabile Paraşüt, de exemplu, necesită credențialele de client și parola acelui sistem. lg nu acceptă niciodată o astfel de valoare ca flag, pentru că ar ajunge în istoricul shell-ului și în output-ul ps: o cere fără ecou sau o citește din ---file=PATH ori din stdin (---file=-) și o păstrează doar în memorie. O comandă al cărei parametru obligatoriu este secret rulează doar din lg: apelată din chat, prin MCP sau în interiorul lg batch, este refuzată cu SECRET_REQUIRES_CLI. Registrul de audit consemnează întotdeauna valoarea ca ***.
Conectarea cu o cheie API
Un ERP, un CRM, un script sau un agent AI se conectează la Logistivo cu o cheie de integrare emisă în panou sau cu lg keys create. Cheia acționează în numele unui membru real al echipei: rolul acelei persoane decide lista de comenzi, nivelul de acces al cheii decide cât de grea poate fi munca, iar când acea persoană pleacă din echipă, cheia dispare odată cu ea. Nu există un „cont de serviciu” sintetic și nici nu va exista — izolarea multi-tenant este legată de utilizator, iar un bridge fără proprietar este genul care continuă să scrie în tăcere ani de zile.
1. Emiteți o cheie în panou — Settings › Integration keys › New key. Dați-i un nume („Sincronizare nocturnă ERP”), alegeți scope-ul și nivelul de acces și, opțional, scurtați durata de viață. Cheia este afișată o singură dată, doar pe acel ecran; serverul nu o stochează. Dacă o pierdeți, Rotate emite una nouă — cea veche devine imediat invalidă.
2. Conectați-vă din terminal — lg login --api-key validează cheia, afișează identitatea și scope-ul și descarcă catalogul de comenzi. lg whoami întreabă serverul cu ce utilizator, companie, rol și scope rulați. lg logout revocă și cheia pe server, la fel cum închide acolo și o sesiune deschisă cu un cod de aprobare (doar lg logout dintr-o sesiune cu parolă nu poate face asta).
3. Sau HTTP simplu — Cheia este un token de acces transmis în antetul Authorization: Bearer și funcționează direct cu cele trei endpoint-uri de comenzi. Pe un server sau în CI, puneți-o în LOGISTIVO_TOKEN; cât timp această variabilă este setată, fișierul de configurare nu este citit niciodată.
4. Sau gestionați cheile din terminal: lg keys — lg keys este geamănul de terminal al ecranului din panou: aceleași endpoint-uri, aceeași poartă (permisiunea de gestionare a echipei și o cheie de nivel manager atunci când o apelați cu o cheie). create, rotate și transfer returnează o singură dată un token nou: cu --save-profile=NAME acesta ajunge direct într-un profil local și nu este afișat niciodată; altfel, lg îl afișează o singură dată. În modul --json, token-ul este inclus doar dacă adăugați --show-secret, iar un apel --json fără niciunul dintre aceste flag-uri este refuzat înainte ca cererea să fie trimisă, astfel încât token-ul nu poate ajunge pe nesimțite în output-ul unui script. rotate, transfer și revoke cer confirmare (--yes); o cheie este adresată prin numele ei exact sau prin uuid, niciodată prin ghicire. Nivelul de acces se transmite neschimbat unei chei rotite sau transferate.
Scope-ul este aplicat pe întreaga suprafață API, nu doar pe catalogul de comenzi: o cheie doar de citire trece de cererile de citire (GET/HEAD/OPTIONS), iar orice altă cerere de scriere răspunde cu 403 forbidden. Există două excepții deliberate și ambele sunt păzite de o poartă mai fină: endpoint-ul de execuție a comenzilor (decizia vine din flag-ul read_only propriu al comenzii, pentru că și comenzile care nu scriu sunt apelate cu POST) și o cheie care se revocă singură (lg logout, permis și pe o cheie doar de citire). Scope-ul, permisiunile pe domenii și nivelul de acces sunt trei axe independente și toate trebuie trecute: o cheie de citire nu poate scrie nici la nivel manager, o cheie de scriere employee nu poate gestiona echipa, iar o permisiune pe domeniul loads:write nu deschide munca de management. Emiteți cheia în numele membrului cu cele mai puține privilegii care vă acoperă nevoile: rolul decide ce înregistrări puteți vedea în primul rând.
read — Catalogul de comenzi și comenzile care nu scriu (list, search, preview). O comandă de scriere returnează 403 forbidden — înaintea porții de confirmare; o cheie doar de citire nici nu vede vreodată un 409. Alegerea potrivită pentru sincronizarea nocturnă și raportare.
write — Orice comandă. Comenzile care necesită confirmare o cer în continuare cu 409; confirm: true (--yes în CLI) funcționează exact ca înainte. Scope-ul nu relaxează niciodată poarta de confirmare.
employee — Implicit pentru orice cheie nouă. Operațiunile de zi cu zi: încărcături, cereri de transport, oferte, curse, flotă și documente de flotă, documente, contacte — orice comandă care nu necesită permisiune de management, plus permisiunile de flotă. O comandă care necesită mai mult răspunde cu 422, cu error_key INSUFFICIENT_KEY_LEVEL și required_key_level: manager; endpoint-ul REST corespunzător răspunde cu 403 și aceeași cheie. Nivelul potrivit pentru o sincronizare nocturnă ERP, un bridge de telematică sau un script de operațiuni.
manager — Tot ce poate face persoana în numele căreia acționează cheia, inclusiv managementul: membri ai echipei și roluri, setările companiei, chei de integrare, conturi bancare și verificarea lor, carduri salvate, relațiile dintre companii, plăți către afiliați. O cheie manager nu adaugă niciodată un drept pe care persoana nu îl are — fără permisiunea de gestionare a echipei, tot nu poate gestiona echipa. Cheile care existau înainte de introducerea nivelurilor de acces sunt chei manager, așa că se comportă exact ca înainte.
O cheie per integrare — Dacă CRM-ul și ERP-ul partajează o cheie, a tăia accesul unuia înseamnă a-l tăia și pe al celuilalt. Dați fiecărui bridge propria cheie; lista le afișează oricum după nume.
Rotire — Emite un token nou și îl revocă imediat pe cel vechi; durata de viață rămasă se păstrează. Folosiți-o la suspiciunea unei scurgeri și la intervale regulate. Integrarea primește 401 până când este actualizată cu noul token.
Revocare — Cheia este închisă definitiv; acțiunea nu poate fi anulată, emiteți o cheie nouă dacă este nevoie. Dacă membrul în numele căruia acționează cheia este eliminat din echipă sau dezactivat, cheia cade de la sine.
Durată de viață și limită — Valabilitatea implicită este de 180 de zile; o puteți scurta la creare, dar niciodată prelungi. Un utilizator poate deține cel mult 10 chei active. Momentul ultimei utilizări este vizibil în listă; o cheie nefolosită niciodată afișează explicit acest lucru.
Cine gestionează — Emiterea, rotirea, transferul și revocarea sunt deschise managerilor cu permisiunea de gestionare a echipei — aceeași poartă ca la adăugarea sau eliminarea membrilor echipei — iar, când se fac cu o cheie de integrare, acea cheie trebuie să fie de nivel manager. Un manager poate emite o cheie în numele altui membru; pentru un bridge se recomandă un membru dedicat, cu drepturi restrânse.
Primele zece minute: de la panou la primul apel
Cele mai costisitoare minute ale unei integrări sunt primele zece. Cei patru pași de mai jos parcurg acest drum în ordine; aceeași ordine există în panou sub forma unui asistent de configurare (Settings › Integration › Setup wizard), iar asistentul apelează exact endpoint-urile descrise aici. Un dezvoltator fără acces la asistent ajunge în același loc citind această secțiune.
Niciunul dintre cei patru pași nu se încheie cu „l-am trimis”. Dacă cheia funcționează cu adevărat aflați din registrul de cereri; dacă webhook-ul ajunge cu adevărat aflați din registrul de livrări. Ambele sunt deschise în panou și în lg. O configurare care nu este măsurată niciodată este o configurare despre care doar se crede că funcționează.
1. Decideți ce veți face — setați mai întâi scope-ul — Nu se poate decide ulterior ce poate vedea o cheie: alegeți scope-ul atunci când o emiteți. Există două axe. Scope-ul grosier (read / write) răspunde doar la întrebarea „poate scrie”. Scope-ul fin (permisiuni pe domenii: loads:read, invoices:write) spune ce domenii poate atinge, iar din momentul în care este setat, cheia devine fail-closed — fiecare domeniu pe care nu l-ați selectat și fiecare endpoint care nu corespunde niciunui domeniu returnează 403. Lista de domenii din panou nu este o listă scrisă de mână; este derivată din catalogul live de comenzi al rolului dumneavoastră și arată câte comenzi și endpoint-uri REST deschide fiecare domeniu. Catalogul de comenzi și endpoint-urile „cine sunt” (current) și „deconectare” sunt întotdeauna exceptate de la scope: o cheie trebuie să se poată descrie și închide întotdeauna singură. A treia axă este nivelul de acces: employee (implicit) rulează operațiunile de zi cu zi, manager face și muncă de echipă, setări, chei și bani. Alegeți employee, cu excepția cazului în care bridge-ul face muncă de management.
2. Emiteți cheia — token-ul este afișat o singură dată — Settings › Integration › New key. Dați-i un nume („Sincronizare nocturnă ERP”), alegeți utilizatorul în numele căruia rulează și nivelul de acces și, dacă doriți, scurtați durata de viață. Token-ul brut este returnat doar în acel răspuns; serverul nu îl stochează și în panou nu există „afișează din nou”. Dacă îl pierdeți, faceți o rotire pentru a obține unul nou, iar cel vechi încetează instantaneu să funcționeze. Nu puneți niciodată token-ul în sistemul de control al versiunilor, într-un log de CI sau într-o fereastră de chat; puneți-l în depozitul de secrete al sistemului țintă.
3. Faceți primul apel — și vedeți că a sosit CU ADEVĂRAT — Două cereri sunt suficiente. Prima vă dovedește identitatea (este exceptată de la scope și funcționează cu orice cheie): scope-ul este cel așteptat, statusul este activ, se apropie expires_at? A doua citește date reale din domeniul pe care l-ați ales. Dacă trece, identitatea, scope-ul, poarta de e-mail și calea de rețea sunt toate corecte. Dacă nu, nu ghiciți: registrul propriu de cereri al cheii arată, rând cu rând, ce endpoint a fost respins, cu ce cod și cu ce cheie de eroare stabilă (INSUFFICIENT_SCOPE, IP_NOT_ALLOWED, KEY_ACTOR_BLOCKED …). În panou, acel registru este fereastra „Recent requests”; în terminal este lg logs. Asistentul de configurare urmărește exact acest registru și refuză să coloreze pasul în verde până când nu vede un apel reușit real.
4. Configurați webhook-ul — și verificați semnătura înainte de orice — Așteptarea evenimentelor este mai ieftină decât întrebarea în fiecare minut. Înregistrați o adresă https, alegeți evenimentele care vă interesează și legați abonamentul de cheia dumneavoastră: dacă cheia este revocată, livrarea se oprește și ea. Secretul este afișat o singură dată, la creare. Endpoint-ul receptor trebuie să verifice mai întâi semnătura: șirul semnat este "{t}.{corp brut}", iar algoritmul este HMAC-SHA256; timestamp-ul se află ÎN semnătură, așa că respingeți orice cerere mai veche de 300 de secunde, chiar și atunci când semnătura este validă. Comparați în timp constant și nu reserializați niciodată corpul — în momentul în care parsați JSON-ul și îl afișați din nou, semnătura nu se mai potrivește. Din panou, „Send test” declanșează un ping semnat real și puteți urmări livrarea încercare cu încercare.
Sandbox: exersați scrierea fără a atinge producția
Preflight-ul (dry_run) vă spune ce AR face o comandă; dar dacă idempotența chiar reia, dacă webhook-ul chiar este livrat, cum arată ramurile de eroare și de unde provine creditul se poate vedea doar la o scriere REALĂ. La asta folosește sandbox-ul: un tenant separat care oglindește compania dumneavoastră — același cod, același catalog de comenzi — și care nu atinge niciodată registrul live.
Sandbox-ul nu este un flag al cererii, este un TENANT. O companie Logistivo separată, deschisă pentru a dumneavoastră: propriul utilizator, propriul pachet, propriul registru de credite, propriile abonamente webhook. Mediul este DEDUS din compania cheii și nu poate fi furnizat de apelant, așa că, chiar dacă alegeți profilul greșit, cererea se oprește pe server cu 403 ENVIRONMENT_MISMATCH. „Credeam că scriu în sandbox și am scris în producție” este imposibil prin structură.
Suprafața este identică — măsurat: catalogul pe care îl obține o cheie sandbox este același cu cel pe care îl obține cheia live (pe o cheie de expeditor, 646 de comenzi de ambele părți). Un bridge care funcționează în sandbox funcționează și în producție; nimic din ce învățați nu trebuie învățat de două ori.
Sandbox-ul nu se deschide gol: conține date inițiale generate (NU copiate) — contacte, încărcături în ambele direcții și cereri de transport. Numele sunt în mod vădit inventate, iar adresele de e-mail se află în domeniul @sandbox.invalid; niciun rând al vreunui tenant real nu este citit, clonat sau folosit vreodată ca șablon.
În mod deliberat NU există un buton de resetare și nicio înregistrare, niciun fișier și niciun document nu este șters vreodată. Dacă doriți un nou început curat, reînnoirea deschide o generație nouă, iar cea veche rămâne, retrasă. Câteva sute de rânduri de repetiție acumulate nu costă nimic pe lângă o rutină de ștergere legată de tenant-ul greșit.
1. Deschideți sandbox-ul — Un sandbox per companie. Endpoint-ul necesită permisiunea de gestionare a echipei (team.manage), așa că acest pas îl face un administrator din compania dumneavoastră. Dacă sandbox-ul există deja, același endpoint răspunde prin GET cu starea lui: id-ul companiei, creditul rămas, numărul de chei active, abonamentele, istoricul generațiilor și plafoanele.
2. Emiteți o cheie sandbox și păstrați-o ca al doilea profil — Cheia este emisă în numele utilizatorului bridge propriu al sandbox-ului și revine marcată environment: sandbox; token-ul brut apare doar în acel unic răspuns. Pe partea lg, nu vă înlocuiți cheia live — păstrați-le pe AMÂNDOUĂ ca profiluri separate; --sandbox și --live sunt selectoare pentru o singură rulare.
3. Scrieți efectiv — Fără --dry-run aici; scrierea este tocmai scopul. Trimiteți de două ori aceeași cheie de idempotență și urmăriți cum al doilea răspuns revine ca status: replayed — acesta este rezultatul măsurat în sandbox. Apelați intenționat o comandă supusă confirmării fără confirmare și citiți corpul 409; încercați o comandă din afara scope-ului și citiți refuzul. Nimic din toate acestea nu lasă urme în registrul live: soldul live rămâne neschimbat pe parcursul aceleiași rulări.
4. Citiți lista de verificare înainte de go-live — Endpoint-ul go-live răspunde pe baza a ceea ce ați făcut EFECTIV în sandbox: ați scris, ați văzut ramurile de eroare, a fost livrat un webhook, ați mutat receptorul de pe adresa de repetiție, ați pus o dată de expirare pe cheie. Fiecare element revine ca pass / todo / unknown. Același răspuns conține și o PROPUNERE DE SCOPE derivată din comenzile pe care le-ați apelat efectiv — folosiți-o pentru a emite cheia live nu mai largă decât aveți nevoie.
Credit și facturare — Sandbox-ul are propriul registru de credite, iar soldul live nu se modifică. Aceasta este o structură, nu o verificare: creditul este contabilizat per companie, iar sandbox-ul este o companie separată. Se deschide pe nivelul gratuit, nu are metodă de plată și se află în afara ferestrei lunare de încasare — nu poate ajunge la o factură pe nicio cale.
Marketplace — O cerere de transport deschisă în sandbox NU apare pe ecranele transportatorilor reali și NU ajunge în căsuța lor de e-mail sau de notificări push; nici dumneavoastră nu vedeți cereri reale. Separarea este simetrică și aplicată în două interogări distincte: cui îi este VIZIBILĂ o cerere și cui îi este TRIMISĂ sunt întrebări diferite.
Webhook-uri — Și abonamentele poartă marcajul de mediu. Un eveniment din sandbox nu este livrat niciodată unui abonament live, iar un eveniment live nu ajunge niciodată la unul din sandbox; pentru un abonament al cărui marcaj a deviat, nu se deschide nicio livrare. Deoarece plafonul de abonamente este per companie, abonamentele de repetiție nu vă consumă din cota live.
Date inițiale — Înregistrările de exemplu din sandbox sunt GENERATE, niciodată copiate de la tenanți reali. Popularea este idempotentă: un al doilea apel nu așază un al doilea set de date inițiale peste propriile dumneavoastră înregistrări.
Același catalog — Rolul dumneavoastră rămâne același și în sandbox, iar lista de comenzi este identică — măsurat, 646 de comenzi de ambele părți. Sandbox-ul nu este un demo redus; este un geamăn al companiei dumneavoastră.
Limita de astăzi: abonamentele webhook nu pot fi gestionate cu o cheie sandbox — Endpoint-urile de abonament necesită permisiunea de gestionare a echipei (team.manage), iar utilizatorul bridge al sandbox-ului nu are niciun rol în echipă, așa că `lg --sandbox webhooks …` răspunde astăzi cu 403. Întreaga suprafață de comenzi funcționează — restricția privește doar registrul de abonamente. Dacă doriți să repetați webhook-urile în sandbox, contactați suportul; acest gol este măsurat și înregistrat ca problemă deschisă.
GET /api/common/integration-sandbox — Starea: dacă există, ce companie, creditul rămas, numărul de chei active și de abonamente, istoricul generațiilor, plafoanele și un ghid de declanșare care arată ce comandă generează ce eveniment.
POST /api/common/integration-sandbox — Deschide sandbox-ul (unul per companie, idempotent). Necesită permisiunea team.manage.
POST /api/common/integration-sandbox/keys — 201 + cheia și token-ul brut (doar aici, o singură dată). Marcajul environment: sandbox este derivat din companie; apelantul nu îl poate furniza.
GET /api/common/integration-sandbox/go-live — Lista de verificare go-live și o propunere de scope — calculate din traficul dumneavoastră real în sandbox.
POST /api/common/integration-sandbox/renew — Deschide o GENERAȚIE nouă de sandbox și o retrage pe cea anterioară.
Modelul de comandă
Există o singură gramatică și nu are excepții. Pentru a ști cum să apelați o comandă, tot ce vă trebuie este ce spune catalogul despre ea.
lg loads list --status=in_transport --limit=20 --json
Numele flag-urilor sunt numele parametrilor din schemă, iar lg acceptă ambele grafii: --load_code și --load-code ajung în același câmp (lg help afișează forma kebab-case). Văzând un flag, știți deci în ce câmp JSON ajunge, iar trecerea de la CLI la HTTP nu necesită nicio traducere de nume. Un parametru boolean scris fără valoare este true (--only_open); opusul este --no-only_open. Scrieți un argument a cărui valoare începe cu o liniuță sub forma --flag=value, altfel un flag uitat înghite în tăcere următorul argument ca valoare. Pe o comandă care primește un fișier, puneți @ în fața unei căi locale (--attachment_uuid=@./cmr.pdf) — vedeți Comenzi care primesc fișiere.
lg — Clientul.
loads — Domeniul — entitatea asupra căreia lucrați, la plural.
list — Verbul — ce faceți cu acea entitate, ales dintr-un vocabular închis care crește doar prin decizie deliberată: verbe simple (list, get, create, update, delete, search, preview, generate, extract …) și verbe compuse care numesc ce se atașează sau ce se schimbă (add-document, set-status, assign-driver). lg help listează verbele unui domeniu.
--status=in_transport — Un parametru — numele lui este exact numele parametrului din JSON Schema, iar valoarea trebuie să corespundă tipului din schemă. O valoare invalidă pe un câmp enum nu ajunge niciodată la server.
--limit=20 — Numărul de rânduri la comenzile de listare. Plafonul este indicat în descrierea parametrului fiecărei comenzi — de regulă 20 la un apel simplu de listare și până la 100 în modul de sincronizare (cu cursor sau updated_since).
--json — Output JSON brut.
--json — Afișează JSON brut. Aceasta este singura formă corectă pentru scripturi: tabelul aliniat implicit este pentru oameni, își alege coloanele din date și își poate schimba aspectul fără preaviz. Nu scrieți niciodată un script care parsează output-ul tabelar.
--yes, -y — Trece de poarta de confirmare (confirm: true prin HTTP). Folosiți-l doar într-un script care știe ce urmează să facă; pe o comandă ireversibilă, acest flag este o prescurtare pentru „nu există cale de întoarcere”.
--idempotency-key= — Face sigură reîncercarea unei comenzi de scriere. Un al doilea apel cu aceeași cheie nu rulează din nou comanda; returnează primul rezultat. Dacă construiți o buclă de reîncercare, generați cheia DUMNEAVOASTRĂ și trimiteți-o pe aceeași la fiecare încercare.
--dry-run — Rulează un preflight în locul comenzii: validarea, porțile și calculul creditelor rulează, nu se scrie nimic (vedeți secțiunea despre preflight). Valabil pentru orice comandă și pentru lg batch.
--refresh — Forțează reîmprospătarea catalogului. lg păstrează catalogul în cache timp de o oră; dacă știți că o comandă tocmai a fost adăugată pe server, folosiți acest flag în loc să așteptați.
--help, -h — Afișează descrierea comenzii din catalog, fiecare parametru, tipul lui, valorile enum și dacă este obligatoriu. În client nu există niciun fișier de ajutor.
--profile=, --sandbox, --live — Profilul cu care se rulează acest singur apel. --sandbox și --live aleg profilul care deține o cheie sandbox, respectiv una live; mediul este dedus din cheie pe server, așa că o nepotrivire se oprește cu 403 ENVIRONMENT_MISMATCH în loc să scrie în locul greșit.
--base-url, --timeout, --verbose, --no-color, --version — În ordine: direcționează o comandă spre alt server, un timeout în secunde, detaliile cererii/răspunsului, dezactivează culoarea ANSI și versiunea clientului.
Exemple reale
Fiecare comandă de mai jos există astăzi în catalog; niciun nume și niciun parametru de aici nu este inventat. Output-urile sunt prescurtate. Output-urile arată nivelul `data.result`; prin HTTP, același obiect sosește în interiorul plicului `{success, data:{…}}` (vedeți Command API prin HTTP).
Încărcături aflate acum pe drum — lg loads list --status=in_transport --limit=20
O încărcătură completă, JSON brut — lg loads get --load_code=FSK2158 --json
Semnalări deschise de consistență a documentelor — lg loads list-problems --only_open=true --limit=10
Rezolvați țara — lg countries search --query=Germany --json
Filtrați cu id-ul rezolvat — lg loads list --receiving_country_id=57 --date_from=2026-09-01 --limit=20
Găsiți un cod HS pornind de la numele unui produs — lg tariffs search --query="aluminium profile"
Avansați o încărcătură (doar rolul de transportator) — lg loads set-status --load_code=FSK2158 --status=transit --date=2026-08-21 --yes
Ciornă — lg export-documents create --doc_type=proforma-invoice --currency_code=EUR --json
Generați documentul (cu confirmare) — lg export-documents generate --document_id=8412 --yes
Fără client: Command API prin HTTP
lg este o comoditate, nu ușa de intrare. Atât catalogul, cât și execuția trec prin trei endpoint-uri HTTP (fișierele au un al patrulea, endpoint-ul de încărcare — vedeți Comenzi care primesc fișiere); o integrare ERP sau CRM se conectează direct aici. Identitatea este un token de acces personal transmis în Authorization: Bearer. FIECARE răspuns vine în același plic: `{ "success": bool, "data": { … }, "code": "…", "message": { … } }`. Întregul contract se află în `data` — `contract_version`, `command`, `status` și, ca output al comenzii, `result`; la eșec `error_code`, `error_key` și `error`. Exemplele de răspuns de pe această pagină arată obiectul `data` în locul plicului, pentru a economisi spațiu; nu uitați să despachetați `data` în propriul cod. `lg --json` afișează și el ÎNTREGUL plic, de aceea căile jq încep cu `.data.result…`. Singura excepție este `/api/public/status`: acest endpoint nu are plic, astfel încât scripturile de supraveghere pot trimite alerte fără să-l parseze.
Cererea de confirmare prin 200 + ok:false este interzisă și nu se va întâmpla niciodată. Motivul este simplu: clienții tratează 200 drept succes, așa că o cerere de confirmare returnată ca 200 ar opri fluxul în tăcere și nimeni nu ar observa. Confirmarea este întotdeauna 409.
GET /api/common/commands — Întregul catalog pe care îl poate vedea rolul dumneavoastră: contract_version; pentru fiecare comandă name, domain, verb, descrierea, JSON Schema, read_only, confirmation_needed, irreversible, credit_cost, since, deprecated_at, replaced_by, aliases și câmpurile de acces key_level, permission, file_params, secret_parameters și cli_only; la nivelul superior dicționarul error_keys, rate_limits, idempotency_ttl_hours, rolurile de catalog ale dumneavoastră, contractul attachments (încărcare) și nivelul de acces al cheii cu care apelați. Trimite un ETag; If-None-Match răspunde cu 304. ?domain= se potrivește și cu un domeniu vechi (alias). Construiți-vă clientul pe baza acestuia; nu scrieți în cod o listă fixă de comenzi.
GET /api/common/commands/{name} — O singură comandă, complet. name este numele înghețat al comenzii din catalog (list_loads), nu identitatea CLI. O comandă depreciată răspunde cu un antet X-Deprecated.
POST /api/common/commands/{name} — Execuția. Corp: { args, confirm?, idempotency_key? }. Statusul HTTP al răspunsului este chiar rezultatul — orice altceva decât 200 este informație, nu zgomot. Erorile poartă error_code (transport) și, pentru respingerile de business, error_key.
Comenzi care primesc fișiere
38 de comenzi din tabel primesc un document sau o fotografie: atașarea unui CMR la o încărcătură, citirea codurilor HS dintr-o factură, crearea unui vehicul din certificatul său de înmatriculare, estimarea unui palet din fotografii, încărcarea unui document al companiei, verificarea încrucișată a unei facturi cu o listă de colisaj. În browser trageți fișierul într-un formular; oriunde altundeva sunt necesari doi pași — încărcați fișierul, apoi transmiteți id-ul lui comenzii.
Un parametru primește un fișier atunci când numele lui se termină în attachment_uuid sau attachment_uuids — photos[].attachment_uuid în interiorul unei liste, front_attachment_uuid pe un cec. Nu trebuie să rețineți asta: fiecare rând din catalog poartă file_params cu căile exacte, schema marchează acele câmpuri (format: uuid, x-logistivo-file: true), iar răspunsul catalogului conține un bloc attachments cu adresa de încărcare, tipurile acceptate, limitele de dimensiune și durata de valabilitate. lg help le afișează și el.
Încărcarea este o scriere, așa că o cheie cu scope de citire nu poate încărca; orice cheie cu scope de scriere poate, la oricare nivel de acces. Încărcările aparțin utilizatorului, nu cheii: două chei ale aceluiași utilizator văd aceleași încărcări și nimeni nu le poate folosi pe ale altcuiva. Un id necunoscut, expirat sau care nu vă aparține pur și simplu nu este găsit, iar motivul nu este dezvăluit.
Atașamentele din chatul panoului de control și încărcările pentru comenzi sunt spații separate: un fișier atașat în chatul asistentului nu poate fi transmis unei comenzi prin id, iar o încărcare pentru comenzi nu apare niciodată într-un fir de chat.
O încărcare nu este o comandă și nu are de una singură niciun efect de business: datelor dumneavoastră nu li se întâmplă nimic până când o comandă nu folosește id-ul. Tot de aceea încărcarea nu cere niciodată confirmare — comanda care consumă fișierul poartă poarta.
1. lg: puneți @ în fața unei căi locale — lg încarcă mai întâi fișierul, apoi rulează comanda cu id-ul returnat; o valoare fără @ este id-ul unui fișier pe care l-ați încărcat anterior. Listele primesc căi separate prin virgulă sau un flag repetat, câmpurile imbricate primesc JSON, iar --file este o scurtătură atunci când comanda are exact un câmp de fișier de nivel superior. lg verifică local fiecare fișier (existență, dimensiune, tip) înainte de a trimite ceva, iar lg batch încarcă o singură dată fiecare fișier distinct înainte de rularea lotului.
2. HTTP: încărcați, apoi transmiteți attachment_uuid — Trimiteți fișierul ca multipart/form-data într-un câmp numit file. O încărcare nouă răspunde cu 201; același fișier încărcat din nou de același utilizator răspunde cu 200, cu statusul replayed și același id, și nu se scrie nimic. Ca peste tot pe această pagină, exemplul arată obiectul data din interiorul plicului.
3. MCP: instrumentul upload_attachment — Un client MCP nu poate trimite multipart, așa că acest canal oferă un instrument suplimentar care nu se află în catalog: upload_attachment primește un nume de fișier și conținutul în base64 și returnează același attachment_uuid. Apelează același serviciu ca încărcarea prin HTTP, după aceleași reguli.
Tipul provine din conținut — Numele fișierului și tipul declarat sunt ignorate; extensia stocată este cea detectată. Acceptate la încărcare: jpg, jpeg, png, webp, heic, heif, pdf, xlsx, xls, csv, txt, doc, docx, xml, zip. Fiecare comandă aplică apoi propria listă, mai restrânsă, înainte de a rula ceva și răspunde cu UNSUPPORTED_FILE_TYPE împreună cu tipurile acceptate, sau cu FILE_TOO_LARGE.
Dimensiune — Imagini de până la 10 MB, alte fișiere de până la 15 MB.
Durată de valabilitate — O încărcare poate fi folosită 24 de ore. După aceea nu mai este rezolvată (ATTACHMENT_NOT_FOUND) — nu este ștearsă. Încărcați din nou dacă o comandă eșuează din acest motiv.
Același fișier, același id — Încărcarea din nou a aceluiași fișier (același nume, aceeași dimensiune și același conținut) returnează id-ul existent în loc să scrie unul nou, atâta timp cât mai are cel puțin o oră de valabilitate, și nu consumă din plafonul zilnic.
Plafoane zilnice — 300 de încărcări per utilizator pe zi (TOO_MANY_FILES) și 2 GB per companie pe zi (DAILY_LIMIT_REACHED); ambele răspund cu 429 și retry_after.
POST /api/common/commands:upload — Încărcare multipart în câmpul file. 201 pentru o încărcare nouă, 200 cu statusul replayed pentru același fișier. Returnează data.attachment: attachment_uuid, filename, mime_type, size_bytes, sha256, extraction_status, expires_at și reused.
Poarta de confirmare și comenzile ireversibile
Fiecare comandă din catalog poartă două flag-uri: confirmation_needed (necesită aprobare explicită înainte de rulare) și irreversible (efectul ei poate fi anulat sau nu). Sunt întrebări separate și ambele sunt aplicate pe server, nu lăsate la bunele maniere ale clientului.
Poarta ține de responsabilitate, nu de regulile de business. Plasarea unei oferte este primul pas spre un contract de transport; emiterea unei facturi creează o înregistrare contabilă; o mișcare de stoc modifică un registru. Niciuna dintre acestea nu ar trebui să fie vreodată ceva ce puteți rula de două ori din greșeală.
Poarta se citește din comanda EFECTIVĂ. Când o comandă o înglobează pe alta — așa cum face executorul generic din chat — poarta provine din flag-urile comenzii care va rula efectiv, nu din cea care o înglobează. Cu un flag fix, unul dintre două eșecuri ar fi inevitabil: fie comanda de facturare ar rula neconfirmată, fie fiecare căutare de țară ar afișa un card de confirmare.
read_only și fără poartă de confirmare nu sunt același lucru. Există trei stări distincte: invoices preview nu e supusă confirmării și nu scrie nimic; loads create e supusă confirmării și scrie; invoices create nu e supusă confirmării, dar scrie — ia naștere o ciornă. Un singur test lămurește: când comanda se întoarce, s-a schimbat vreun rând în baza de date?
Unele acțiuni nu se află în spatele acestei porți pentru că nu sunt deloc comenzi: cumpărarea unui pachet, adăugarea unui card cu 3D Secure, aprobarea textelor legale și închiderea unui cont au loc în browserul propriu al persoanei. Pentru acestea, lg handoff-links generate returnează un link logistivo.com — gratuit, fără să scrie nimic, fără să poarte vreun secret — iar persoana finalizează pasul acolo. Niciun flag, oricum ar fi setat, nu transformă o plată sau un consimțământ într-un apel API.
Tehnic, este posibil ca o integrare să treacă automat de poartă la fiecare apel, dar nu este recomandabil. Modelul corect este să automatizați poarta doar pentru comenzile despre care știți că sunt reversibile și să direcționați comenzile ireversibile spre coada unui om.
1. Apelați — Apelați comanda supusă confirmării fără confirm. Nu se schimbă nimic.
2. Citiți rezumatul — Primiți un 409; confirmation.summary din corp este o propoziție scrisă pentru un om („Urmează emiterea unei facturi: X Ltd, 1.200,00 TRY”), nu o descărcare de argumente brute. Comenzile monetare poartă și o previzualizare structurată: linii, totaluri, avertismente.
3. Confirmați — Repetați același apel cu confirm: true (--yes în CLI). Comenzile ireversibile sunt marcate astfel încât să ruleze cel mult o dată.
Preflight: vedeți ce ar face o comandă de scriere, fără să o rulați
Cel mai costisitor pas în conectarea unui bridge ERP este să aflați dacă un corp de cerere este corect rulând EFECTIV comanda: o ciornă de factură în registrul live, un credit consumat, curățenie manuală. dry_run pune capăt acestui lucru — adăugați un singur câmp la cerere, comanda nu rulează, iar dumneavoastră citiți ce s-ar întâmpla.
Registrul conține astăzi 721 de comenzi; 327 dintre ele doar citesc și nu scriu nimic. Dintre cele 394 de comenzi de scriere rămase, 346 sunt supuse confirmării: apelate fără confirm, ele răspund deja cu 409 și descriu ce ar face. Golul era la celelalte 48 — ciorne de factură, ciorne de documente de export, linii de articole: exact lanțul pe care un bridge îl conectează primul. Pentru acestea, a apela însemna a executa.
Exista un al doilea gol chiar și la comenzile supuse confirmării: validarea schemei rulează DUPĂ poartă. Astfel, un apel cu un argument lipsă primea mai întâi cardul de confirmare, îl confirma și abia apoi afla „acest câmp lipsește”. Un preflight răspunde la ambele într-un singur dus-întors.
Iar cel mai frecvent — și cel mai târziu descoperit — bug de bridge este acesta: trimiteți un câmp care nu se află în schemă (customer_id acolo unde se așteaptă recipient_contact_id), serverul îl elimină în tăcere, comanda returnează 200, iar înregistrarea ajunge în locul greșit. Răspunsul preflight listează aceste câmpuri după nume sub arguments.ignored; niciun mesaj de eroare nu o va face vreodată.
Un preflight nu scrie nimic, iar acest lucru ține de structură înainte de a fi o măsurătoare: calea de preflight nu intră niciodată în handler-ul comenzii, deci regula este valabilă pentru orice comandă, inclusiv pentru cele adăugate ulterior. A fost și măsurat la lansare: fiecare instrucțiune SQL emisă în timpul preflight-ului tuturor comenzilor de scriere existente atunci în catalog (două seturi de argumente, două roluri, 178 de preflight-uri) a fost capturată. Niciun INSERT/UPDATE/DELETE, niciun job pus în coadă, niciun e-mail; numărul de rânduri din 31 de tabele și soldul de credit au rămas neschimbate.
Codul de ieșire este același pe care l-ar produce apelul real — comanda ar rula: 0, poarta de confirmare 4, conflict de idempotență 2, orice altceva 1 — așa că „lg … --dry-run || exit” este o poartă cu sens într-un pas de CI.
1. Apelați cu dry_run — Adăugați "dry_run": true în corpul cererii. Validarea, poarta de rol și de scope, rezolvarea țintelor și calculul creditelor rulează toate; comanda nu.
2. Citiți would_execute — Acesta este singurul flag după care să ramificați. Când este false, would_stop.at numește locul în care s-ar opri un apel real: idempotency, target_precheck, confirmation_gate sau arguments.
3. Corectați corpul cererii — arguments.ignored numește câmpurile care ar fi eliminate în tăcere, missing_required pe cele obligatorii pe care le-ați omis, iar would_charge câte credite s-ar consuma și dacă soldul le acoperă.
4. Renunțați la dry_run — Repetați până când would_execute este true, apoi eliminați flag-ul și faceți apelul real. Cheia de idempotență trimisă în timpul preflight-ului nu a fost consumată, așa că apelul real rulează normal.
HTTP este întotdeauna 200 — „Comanda ar eșua” nu sosește niciodată ca 4xx — preflight-ul în sine a reușit, iar predicția se află în corp. Excepția este un refuz la nivel de transport, iar acolo se comportă exact ca un apel real: 404 comandă necunoscută, 403 rol/scope, 429 limită de rată.
O cheie cu scope de citire nu poate face dry-run pe o comandă de scriere — Primește 403. Un preflight răspunde la întrebarea „ce se întâmplă dacă apelez asta CU ACEASTĂ CHEIE, acum”; a da undă verde unei chei de citire și apoi un 403 la apelul real ar fi exact surpriza pe care preflight-ul există să o prevină.
Cheia de idempotență nu este consumată — O cheie trimisă în timpul unui preflight nu deschide niciun rând în registru, iar un blocaj expirat nu este eliberat. Așadar, trimiteți cheia pe care intenționați să o folosiți de fapt: preflight-ul vă spune dacă este încă liberă, dacă ar relua o rulare anterioară sau dacă intră în conflict cu altă comandă.
Se combină cu confirm — Trimiteți dry_run și confirm împreună, iar întrebarea devine „dacă confirm, ce se întâmplă?”. Tot nu rulează nimic.
Preflight-ul pentru batch este per lot — commands:batch acceptă și el dry_run, dar flag-ul aparține lotului, nu unui element (trimiterea lui pe un element înseamnă 422). Primiți un raport per element plus costul total în credite al lotului; un sold insuficient este raportat, nu refuzat.
Nu este gratuit — Fiecare preflight rulează interogări reale (previzualizare, sold) și se contorizează în limita de rată. Nu faceți preflight pe întregul catalog la fiecare deploy; faceți preflight pe comenzile pe care le-ați modificat.
Idempotență: de ce reîncercarea nu creează duplicate
Un ERP nu vă citește mesajul de eroare, nu vă vede ecranul și va retrimite aceeași cerere după un timeout. Această secțiune există exact pentru acest comportament.
Un apel care poartă un idempotency_key (cheie de idempotență) rulează cel mult o dată. Al doilea apel nu reexecută comanda; returnează rezultatul înregistrat cu statusul replayed. Când rețeaua cade, când o cerere expiră sau când o coadă preia același job de două ori, primiți primul rezultat în locul unei facturi duplicate.
Folosiți o cheie la fiecare comandă de scriere. Câmpul read_only din catalog vă oferă gratuit această distincție: fiecare comandă cu read_only: false merită o cheie de idempotență.
Strategia de reîncercare ar trebui să folosească backoff exponențial și să poarte ACEEAȘI cheie la fiecare încercare. A genera o cheie nouă la fiecare încercare este totuna cu a nu folosi deloc idempotența. Nu trimiteți aceeași cheie în paralel: execuția cel mult o dată este garantată pentru reîncercări secvențiale, nu pentru două cereri care se întrec una cu cealaltă.
Capcana 1 — și eșecul este blocat — Dacă prima execuție a fost respinsă de o regulă de business (failed), un al doilea apel cu aceeași cheie returnează aceeași eroare și același error_key și nu reîncearcă. Corectarea argumentului și o nouă încercare necesită o cheie NOUĂ. O cheie reprezintă o încercare, nu o intenție.
Capcana 2 — un rezultat mare se reia fără corp — Registrul stochează un rezultat doar dacă are sub 64 KB. Un rezultat mai mare se reia cu statusul replayed, dar cu un corp gol. Integrarea dumneavoastră ar trebui să se bazeze pe semnalul „replayed”, nu pe corp, și să preia datele cu comanda get corespunzătoare.
Capcana 3 — o cheie aparține unei singure comenzi — Trimiterea aceleiași chei cu o altă comandă returnează 409 idempotency_conflict cu conflicting_command; nu rulează nimic și nu se reia nimic. Un client care partajează o cheie între două verbe este defect și află acest lucru dintr-o eroare, nu dintr-o reluare tăcută.
Capcana 4 — blocajul durează 24 de ore, nu pentru totdeauna — După 24 de ore, aceeași cheie înseamnă o execuție nouă. Reîncercările de rețea sosesc în câteva minute; numerele de document recurente anual ale unui ERP nu trebuie să rămână „replayed” pentru totdeauna. Catalogul publică fereastra ca idempotency_ttl_hours.
Capcana 5 — o eroare de server nu blochează cheia — Un 5xx server_error nu este o respingere de business: cheia nu este legată, așa că o reîncercare cu aceeași cheie rulează cu adevărat comanda. Doar failed blochează (capcana 1).
Domeniu și format — compania dumneavoastră, orice șir, de preferat un UUID — Unicitatea este impusă pe (compania dumneavoastră, cheie): INV-1001 al altui tenant nu se ciocnește niciodată cu al dumneavoastră și nu vă poate relua niciodată rezultatul. Folosiți un UUID simplu sau o compunere unică prin construcție, cum ar fi {ERP-document-no}:{verb}.
Sincronizare incrementală și paginare
Un bridge ERP/CRM ar trebui să preia ce s-a schimbat, nu totul în fiecare oră. Fiecare comandă de listare — loads list, demands list-own, contacts list, invoices list, teammates list, load-groups list, reservations list, drivers list, tenders list, products search, warehouses search — acceptă doi parametri comuni și returnează un câmp comun.
De ce nu există offset: pe un tabel live, un offset alunecă. Un rând inserat între două pagini vă face să săriți peste o înregistrare sau să o numărați de două ori, în tăcere. Cursorul merge doar înainte, așa că o înregistrare inserată sau actualizată în timpul parcurgerii ajunge la sfârșitul listei: nu se pierde nimic, nu se dublează nimic.
O încărcare inițială completă folosește același mecanism: porniți cu updated_since=1970-01-01T00:00:00Z și urmați next_cursor până când este null. Nu există un endpoint separat de „export”, pentru că nu este nevoie de unul.
Același lucru cu lg: lg loads list --updated_since=2026-09-01T00:00:00Z --limit=100 --json, apoi lg loads list --cursor= --json.
Pentru următoarea sincronizare, setați updated_since la cel mai mare updated_at pe care l-ați văzut. Timestamp-urile au precizie de o secundă, așa că o înregistrare aflată la limită poate sosi de două ori — inofensiv, atâta timp cât pe partea dumneavoastră faceți upsert după external_ref sau după cod. Fără updated_since sau cursor, o comandă rulează în modul chat: ordonare pentru oameni, cel mult 20 de rânduri, next_cursor null și truncated care spune „mai există”. Nu folosiți acest mod pentru sincronizare.
Cheile de eroare lizibile automat pentru această secțiune: INVALID_CURSOR, INVALID_UPDATED_SINCE, DUPLICATE_EXTERNAL_REF, EXTERNAL_REF_TOO_LONG, EXTERNAL_REF_INVALID. Toate răspund cu HTTP 422, cu error_code: "failed" și result.error_key în corp. Ramificați după cheie, niciodată după text.
updated_since — Timestamp ISO-8601 (se recomandă UTC, de ex. 2026-09-01T00:00:00Z). Rândurile actualizate la acest moment sau după el. Trece comanda în modul de sincronizare: ordine fixă (updated_at, id) crescătoare, limit plafonat la 100.
cursor — next_cursor din răspunsul anterior, întocmai. Este opac și semnat: nu construiți și nu editați niciodată unul, nu refolosiți niciodată cursorul altei companii sau al altei comenzi; toate acestea sunt respinse cu INVALID_CURSOR.
limit — Dimensiunea paginii. 1-100 în modul de sincronizare (implicit 10).
next_cursor (răspuns) — Cursorul pentru pagina următoare. null înseamnă că lista este completă; este singurul răspuns corect la întrebarea „mai există ceva”.
total (răspuns) — Rândurile care corespund filtrelor, independent de pagină — pentru raportarea progresului.
Propria dumneavoastră cheie: external_ref
Nu faceți din id-urile noastre auto-increment (invoice_id, contact_id) cheia de business din ERP-ul dumneavoastră; ele sunt opace și private pentru compania dumneavoastră. Încărcăturile, cererile de transport, contactele, facturile, produsele și depozitele poartă în schimb cheia dumneavoastră.
Setați-o la scriere — loads create, demands create, contacts create și contacts update, invoices create acceptă un external_ref opțional (maximum 120 de caractere) și îl returnează neschimbat.
Folosiți-o la citire — loads get --external_ref=ORD-2026-0917, invoices get --external_ref=..., contacts get --external_ref=..., demands get --external_ref=... funcționează toate; la comenzile de listare și de căutare, --external_ref= este un filtru de potrivire exactă.
Unică per companie — O a doua înregistrare cu aceeași cheie este refuzată cu 422 și result.error_key = DUPLICATE_EXTERNAL_REF; cheia altei companii vă răspunde „nu a fost găsit”. Potrivirea nu ține cont de majuscule (ord-1 = ORD-1). O înregistrare arhivată își păstrează cheia; restaurați-o înainte de a refolosi cheia.
Trimiteți și un idempotency_key — O reîncercare după un timeout de rețea returnează primul rezultat în loc să creeze un duplicat. Cele două nu sunt interschimbabile: external_ref este cheia dumneavoastră de business, idempotency_key identifică o încercare.
Webhook-uri de ieșire: vă trimitem un POST când se întâmplă ceva
Tot ce a fost până aici era pull: dumneavoastră întrebați, noi răspundem. Un bridge ERP trebuia să întrebe o dată pe minut ca să afle că o încărcătură și-a schimbat statusul, că a fost emisă o factură sau că a sosit o ofertă. Nu mai este cazul: înregistrați o adresă https, alegeți evenimentele care vă interesează, iar un POST semnat sosește atunci când acestea au loc.
Push-ul a fost adăugat LÂNGĂ pull, nu în locul lui. Sincronizarea incrementală (updated_since + cursor) rămâne neatinsă și este în continuare instrumentul potrivit: prima încărcare completă, completarea istoricului și răspunsul la întrebarea „am ratat ceva” țin toate de ea. Webhook-urile reduc latența de la minute la secunde. Un bridge sănătos le folosește pe amândouă — webhook-ul ca declanșator, sincronizarea ca plasă de siguranță.
Payload-ul este un SEMNAL, nu o copie a înregistrării. Poartă identificatorii (id, propriul dumneavoastră external_ref, statusul, momentul); detaliile le preluați cu propria cheie prin GET, iar acel apel trece deja prin propriile dumneavoastră porți de autorizare. Suprafața de expunere rămâne astfel la nivel de identificator. Două câmpuri lipsesc în mod deliberat: identitatea companiei care a plasat o ofertă (ofertele oarbe apar sub un alias în panou; a pune identitatea într-un webhook ar străpunge această confidențialitate printr-un al doilea canal) și datele de contact ale rezervării (nu este nevoie să mutăm date personale printr-un canal suplimentar).
Numele evenimentelor sunt ÎNGHEȚATE. Dacă sensul unui nume se schimbă, se deschide un nume nou, iar cel vechi trăiește pe durata unei ferestre de depreciere. Adăugarea unui câmp nou în payload NU crește versiunea contractului — un consumator trebuie să ignore câmpurile pe care nu le cunoaște.
GET /api/common/integration-webhooks — Registrul plus catalogul de evenimente, limitele și numele antetelor. Fiecare rând poartă motivul dezactivării și un rezumat al livrărilor pe 7 zile.
POST /api/common/integration-webhooks — 201 + { webhook, secret, shown_once: true }. Secretul apare doar aici.
PATCH /api/common/integration-webhooks/{uuid} — Nume / adresă / evenimente / flag de activare. NU atinge secretul.
DELETE /api/common/integration-webhooks/{uuid} — Îl elimină: rândul este șters logic (soft delete; istoricul rămâne interogabil), iar livrările în așteptare sunt anulate.
POST /api/common/integration-webhooks/{uuid}/rotate-secret — 201 + un secret nou. Valoarea veche nu mai funcționează din acel moment.
POST /api/common/integration-webhooks/{uuid}/test — Un eveniment ping — semnătură reală, cale reală, program real de reîncercări.
GET /api/common/integration-webhooks/{uuid}/deliveries — Cele mai recente livrări: status, numărul încercării, codul HTTP, durata, eticheta de eroare.
POST /api/common/integration-webhooks/deliveries/{uuid}/replay — Retrimite o singură livrare: event_id se PĂSTREAZĂ, id-ul livrării este nou, payload-ul este copiat întocmai.
Catalogul de evenimente
Fiecare dintre cele 13 evenimente de mai jos este susținut de o clasă de eveniment care este emisă EFECTIV. În catalog nu există nume de tip „ar fi frumos”: un eveniment anunțat, dar niciodată declanșat, este un eveniment pe care integratorul îl așteaptă la nesfârșit, iar acest eșec este tăcut. Nici acest tabel nu este scris de mână — este construit din catalogul live la fiecare încărcare a paginii.
invoice.payment_recorded LIPSEȘTE în mod deliberat: această clasă de eveniment există în cod, dar nu este emisă de nicăieri. Evenimentul de plată va fi adăugat în ziua în care clasa este declanșată cu adevărat — nu mai devreme. A anunța prematur un eveniment este mai rău decât a nu-l adăuga niciodată.
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)
Verificarea semnăturii
Fiecare cerere poartă un antet X-Logistivo-Signature: t=,v1=. Șirul semnat este ".", iar algoritmul este HMAC-SHA256. Prefixul v1 păstrează schema versionabilă: dacă va apărea vreodată o a doua schemă, antetul va purta t=…,v1=…,v2=…, iar dumneavoastră o alegeți pe cea pe care o cunoașteți.
Publicăm două receptoare de referință fără dependențe, unul pentru Node și unul pentru PHP simplu. Amândouă aplică cele patru reguli de mai sus și se testează singure cu --selftest: semnătură validă, corp alterat, secret greșit, timestamp în afara ferestrei, antet malformat, capcana reserializării și ambele tipuri de repetiție (aceeași livrare / același fapt). Verificatorul este perechea exactă a codului pe care îl folosim noi înșine — consumăm contractul pe care îl publicăm.
Verificați corpul BRUT — Semnătura este calculată pe octeți. Decodarea și reserializarea corpului (JSON.stringify(req.body), json_encode($request->all())) transformă aceleași DATE în OCTEȚI diferiți, iar semnătura nu se mai potrivește. În Node capcana este formatarea numerelor (1.50 pe fir devine 1.5; întregii mari își pierd precizia), în PHP este escaparea caracterelor (/ devine \/, İ devine \u0130). Folosiți express.raw în Express și $request->getContent() în Laravel. Aceasta este cea mai frecventă greșeală la scrierea unui receptor.
Verificați timestamp-ul — t se află ÎN semnătură. Verificarea doar a semnăturii îi permite oricui a capturat o cerere validă să o retrimită ore mai târziu, iar receptorul ar socoti-o drept un eveniment verificat. Respingeți orice cerere pentru care |now − t| > tolerance, chiar dacă semnătura este corectă. Fereastra recomandată este de 300 de secunde.
Comparați în timp constant — hash_equals / timingSafeEqual. Compararea cu == îi permite unui atacator să ghicească semnătura octet cu octet.
Deduplicați după event_id, nu după id — event_id identifică FAPTUL: este același pentru doi abonați care primesc același eveniment și se PĂSTREAZĂ la reluare. id (= X-Logistivo-Delivery) identifică LIVRAREA și se schimbă la reluare. Răspundeți la întrebarea „am tratat deja asta” cu event_id; dacă răspundeți cu id, o reluare va executa aceeași muncă de două ori.
Livrare, reîncercări și dezactivare
Receptorul dumneavoastră nu va fi întotdeauna disponibil. Mecanismul pornește de la această premisă: un eșec tranzitoriu intră în programul de reîncercări, unul permanent dezactivează abonamentul — iar MOTIVUL dezactivării este întotdeauna înregistrat.
Motivul dezactivării este lizibil automat și stabil (delivery_failures, endpoint_gone, unsafe_target, key_revoked, by_user) și apare atât în panou, cât și în `lg webhooks list`. O dezactivare fără motiv ar lăsa fără răspuns întrebarea „de ce nu sosește nimic”. Reactivarea resetează contorul și marcajul.
Dumneavoastră scrieți adresa; serverul NOSTRU face cererea. Fără o poartă, un tenant care ar introduce o adresă de metadate cloud ne-ar putea face să emitem cereri din interiorul propriei noastre rețele. De aceea, adresa este verificată atât la înregistrare, cât și la FIECARE livrare:
Timeout-uri — 8 s în total, 4 s pentru conectare — un receptor lent nu trebuie să ocupe un worker. Puneți munca în coadă și returnați imediat 2xx.
Programul de reîncercări — Intervale (în secunde): 60 · 300 · 1800 · 7200 · 21600 → 6 încercări, o fereastră de aproximativ 8,6 ore.
Singurul eșec permanent: 410 Gone — Înseamnă „ștergeți-mă”: nicio reîncercare, abonamentul este dezactivat imediat. Nu returnați NICIODATĂ 410 pentru un eșec de semnătură.
Orice alt eșec — TOATE sunt reîncercate, inclusiv 4xx. Pierderea unui eveniment de business costă mai mult decât câteva cereri în plus: un receptor care returnează 403 în timp ce o regulă WAF este actualizată ar pierde în tăcere un eveniment „factură emisă” pe un mecanism care tratează 4xx ca permanent.
Retry-After — Respectat la 429 și 503 (plafonat la 6 ore).
Redirecționări — NU sunt urmate. Saltul către o adresă internă printr-un 302 ar străpunge poarta de adrese pe o a doua cale.
Dezactivare automată — După 10 livrări consecutive epuizate. Un 410, o țintă nesigură și revocarea cheii de integrare asociate dezactivează IMEDIAT.
doar https, doar porturile 443/8443, credențialele încorporate (https://user:pass@…) sunt respinse;
localhost, numele dintr-o singură etichetă și sufixele interne precum .internal / .local / .svc sunt respinse — intenția este respinsă înainte ca rezultatul rezolvării să fie măcar consultat, astfel încât un DNS split-horizon nu poate străpunge poarta;
literalele IP și TOATE înregistrările rezolvării DNS trebuie să fie publice. Dacă un nume se rezolvă atât la o adresă publică, cât și la una privată, nimeni nu ne întreabă pe care să o alegem → numele este respins direct;
la momentul livrării, adresa este rezolvată o singură dată, iar conexiunea este fixată pe adresa verificată: fereastra de DNS rebinding este închisă;
CORPUL răspunsului receptorului nu este stocat nicăieri (doar codul de status, durata și o etichetă scurtă de eroare) — astfel, calea de „citire”, care este de fapt ceea ce valorează o breșă în poarta de adrese, rămâne închisă.
În mod deliberat, NU există niciun comutator de configurare pentru „permite adrese private”: un astfel de comutator ajunge într-o zi să fie lăsat pornit din greșeală.
Este returnat O SINGURĂ DATĂ, doar la crearea abonamentului și la rotate-secret. Este stocat criptat pe server și nu poate fi citit niciodată înapoi; nu există „afișează din nou”.
lg îl afișează pe ecran și îl lasă acolo — nu îl scrie în niciun fișier de configurare sau de cache.
Dacă se pierde, îl rotiți; valoarea veche nu mai funcționează DIN ACEL MOMENT. Pentru o trecere fără întreruperi, receptorul dumneavoastră ar trebui să încerce ambele secrete pe durata tranziției.
Schimbarea adresei NU atinge secretul: o întreținere de rutină precum „URL-ul s-a mutat” nu trebuie să strice verificarea pe partea receptoare.
Sănătate și status: nimeni nu ar trebui să observe un bridge tăcut înaintea dumneavoastră
Un bridge de integrare moare rareori zgomotos. De obicei amuțește în orele mici ale nopții: un token expiră, persoana în numele căreia rulează cheia pleacă din echipă, un scope este restrâns sau endpoint-ul receptor începe să returneze 403. Primul care observă este aproape întotdeauna clientul. lg status există pentru a inversa această ordine.
O singură comandă răspunde la două întrebări deodată, pentru că în timpul unei întreruperi ambele sunt puse în același moment: funcționează platforma și este sănătos bridge-ul meu? Linia platformei funcționează fără token — în timpul unei defecțiuni, token-ul însuși este primul suspect, iar legarea întrebării despre status de el v-ar lăsa fără răspuns exact atunci când aveți nevoie de unul.
Rezumatul de sănătate nu ține niciun registru nou; el adună trei surse existente într-o singură propoziție: contorul zilnic de utilizare (cât ați apelat și cât a eșuat), registrul de cereri (ce cerere, când și de ce a fost respinsă) și registrul de livrare a webhook-urilor de ieșire (a ajuns evenimentul la receptor). Rata de eroare se citește întotdeauna din contorul zilnic; registrul de detalii este plafonat și spune clar când plafonul a fost atins.
Același rezumat apare și în panou: la Settings › Integration › Keys, fiecare rând poartă un badge și, sub el, motivul. Pragurile nu sunt calculate pe partea clientului; nivelul atribuit de server este cel pe care îl afișează atât panoul, cât și lg status, astfel încât cele două ecrane nu pot spune niciodată lucruri diferite despre aceeași cheie.
Scriptul dumneavoastră de supraveghere nu are nevoie de token. Endpoint-ul returnează doar cuvinte de status; nu conține versiune, nume de gazdă, nume de coadă, număr de job-uri, text de eroare sau date ale clienților — și nici nu poate conține.
Rezumatul de sănătate este produs cu un număr constant de interogări per cerere; numărul de interogări nu crește odată cu numărul de chei. Pentru detalii, citiți cererile recente ale acelei chei cu lg logs, iar bridge-ul de ieșire cu lg webhooks list.
SĂNĂTOS — Nicio defecțiune măsurată și avem dovada succesului: un apel reușit în registru sau trafic care a rămas fără erori în contor.
ATENȚIE — Ceva a început să se strice: rata de eroare sau seria de eșecuri consecutive a depășit un prag, cererile sunt respinse la poartă, cheia este aproape de expirare sau un bridge care comunica regulat a amuțit.
ÎN EȘEC — Bridge-ul nu funcționează în acest moment: token-ul a fost revocat neintenționat, o cheie închisă este încă apelată, există cinci eșecuri la rând, rata de eroare depășește cincizeci la sută sau un abonament webhook a fost dezactivat.
ÎNCHIS — Cheia a fost închisă deliberat și nimeni nu o apelează. Aceasta este o decizie, nu o defecțiune — și nu este colorată în roșu.
FĂRĂ DATE — Nu există nicio măsurătoare: cheia nu a fost apelată niciodată sau măsurătoarea însăși a eșuat. Niciuna dintre aceste situații nu este verde.
Fără verde fals. Badge-ul de sănătate necesită o dovadă măsurată a succesului; o cheie care nu a fost apelată niciodată nu devine niciodată verde, pentru că nicio măsurătoare nu arată că funcționează.
Fără roșu fals. Cheile pe care le-ați închis intenționat apar ca Închise. A colora totul în roșu golește roșul de sens; o cheie închisă devine roșie doar dacă este încă apelată după închidere — și atunci un bridge chiar este stricat.
„Nu s-a putut măsura” nu este același lucru cu „fără date”. Dacă o interogare eșuează pe server, rândul nu afișează în tăcere zero; spune că măsurătoarea nu a putut fi efectuată.
Tăcerea este întotdeauna raportată, dar niciodată transformată orbește în avertisment. Un bridge de sfârșit de lună care tace treizeci de ore este normal; un bridge care a comunicat în cel puțin cinci din ultimele șapte zile și apoi amuțește este o defecțiune. Ritmul este măsurat, nu presupus.
Interogarea de status nu poluează ea însăși cifrele de sănătate. Apelurile făcute de lg status apar în registrul de cereri, dar sunt excluse din calculul sănătății — altfel propria dumneavoastră interogare de status reușită ar reseta seria de eșecuri și ar ascunde exact defecțiunea pe care ecranul există să o arate.
Fiecare linie este măsurată: se rulează o interogare reală pe baza de date, catalogul de comenzi este construit efectiv, înregistrarea live a worker-ului de coadă este citită efectiv. Nimic nu este presupus.
Răspunsul în sine este și el o măsurătoare: dacă puteți citi corpul, nivelul web funcționează.
Nivelul superior derivă doar din componentele obligatorii. Când coada se oprește, răspunsul este degraded, nu down — un apel API sincron nu are nevoie de coadă, iar declararea platformei ca nefuncțională ar fi o alarmă falsă.
Când starea cozii nu poate fi măsurată, nivelul superior rămâne neatins: a nu ști nu este același lucru cu a măsura că ceva este stricat.
Dacă platforma este căzută, endpoint-ul returnează HTTP 503. Corpul nu are plic, astfel încât instrumentele de monitorizare pot trimite alerte fără să-l parseze, iar răspunsul nu este stocat niciodată în vreun cache.
Erori și coduri de ieșire
Ceea ce folosește o mașină pentru ramificare este un șir stabil. Textul din câmpul error se adresează unui om, este localizat și se schimbă fără preaviz — o integrare care se ramifică după textul mesajului nu este suportată, iar faptul că se strică nu este un bug.
Două taxonomii, două câmpuri. error_code este nivelul de transport (tabelul de mai sus) și este primul după care ramificați. error_key este cheia stabilă a regulii de business din interiorul lui failed — INSUFFICIENT_CREDITS, NOT_FOUND, DUPLICATE_CONTACT, INSUFFICIENT_STOCK — publicată ca dicționar în catalog (error_keys) și mai jos. O comandă care nu emite încă o cheie returnează error_key: null; tratați o cheie care lipsește din dicționar ca pe un eșec generic.
ok — HTTP 200 · error_code — · CLI 0 · —
replayed — HTTP 200 · error_code — · CLI 0 · Reluare idempotentă; munca NU a rulat din nou.
failed — HTTP 422 · error_code failed · CLI 1 · Nu — a fost respinsă de o regulă de business (vedeți error_key). Inutil până când argumentul se schimbă.
needs_confirmation — HTTP 409 · error_code needs_confirmation · CLI 4 · Da, cu confirm: true.
idempotency_conflict — HTTP 409 · error_code idempotency_conflict · CLI 2 · Nu — cheia a fost folosită mai întâi pentru o altă comandă (conflicting_command). Emiteți o cheie nouă.
forbidden — HTTP 403 · error_code forbidden · CLI 3 · Nu — poarta de rol sau o cheie cu scope de citire pe o comandă de scriere.
not_found — HTTP 404 · error_code not_found · CLI 2 · Nu — nume de comandă greșit sau eliminat.
(schemă) — HTTP 422 · error_code invalid_request · CLI 2 · Nu — corpul cererii sau un argument nu a trecut validarea schemei (errors{}); nu este o regulă de business.
server_error — HTTP 500 · error_code server_error · CLI 6 · Da — backoff exponențial cu ACEEAȘI cheie de idempotență; cheia nu a fost blocată.
401 unauthenticated — Token-ul a expirat sau a fost revocat. Reîncercarea nu ajută; token-ul trebuie înlocuit.
429 rate_limited — Limită de rată atinsă pentru acest token. Răspunsul poartă întotdeauna Retry-After și un corp cu retry_after, limit și bucket; respectați-l în loc să inventați o întârziere fixă. lg așteaptă și reîncearcă de până la trei ori, apoi iese cu codul 5.
5xx server_error / eroare de rețea — Reîncercați cu backoff exponențial și cu ACEEAȘI cheie de idempotență. Schimbarea cheii rulează din nou o muncă pe care serverul poate să o fi finalizat deja. lg reîncearcă de trei ori (1 s, 2 s, 4 s), apoi iese cu codul 6 și error_code network_error sau server_error.
Promisiunea de stabilitate
Cea mai costisitoare întrebare dintr-un contract de integrare este „codul pe care îl scriu astăzi va mai rula și mâine?”. Un singur număr îi răspunde: contract_version din catalog și antetul X-Contract-Version de pe fiecare răspuns. El răspunde la exact o întrebare — codul scris anterior rulează în continuare neschimbat? Dacă numărul nu a crescut, da. Dacă a crescut, nu: ceva pe care vă bazați a fost eliminat sau restrâns.
Pentru că un anunț nu elimină nimic: codul existent rulează exact ca înainte, și în ziua de după. Creșterea versiunii la anunț ar emite două semnale pentru o singură schimbare și v-ar obișnui să-l ignorați pe primul — slăbind semnalul care contează cu adevărat. Anunțul călătorește deja odată cu apelul pe care îl faceți: deprecated_at și replaced_by pe rândul din catalog, un antet X-Deprecated plus un bloc deprecated în răspunsul acelei comenzi și un avertisment de o linie pe stderr dacă folosiți lg. Nu trebuie să faceți nimic ca să aflați că ceva va dispărea; este deja în logul dumneavoastră.
Între anunț și eliminare trec cel puțin două trimestre calendaristice. Pe toată durata ferestrei, comanda veche răspunde în continuare și avertizează la fiecare apel. Când un nume CLI este retras, succesorul său preia acel nume ca alias: pe durata ferestrei, numele vechi ajunge la comanda veche, iar în ziua eliminării același apel ajunge la cea nouă — fără ca dumneavoastră să livrați o versiune nouă a clientului.
preview_invoice → get_invoice (anunțat pe 3 septembrie 2026). get_invoice returnează același bloc de previzualizare și adaugă liniile, defalcarea taxelor, plățile înregistrate, soldul rămas și adresarea după propria cheie ERP (external_ref). preview_invoice continuă să funcționeze, la fel și lg invoices preview — ambele avertizează.
fără schimbare — O comandă nouă · un parametru OPȚIONAL nou · un câmp nou în răspuns · o cheie de eroare nouă · un endpoint nou — Nu faceți nimic. Trebuie să ignorați câmpurile pe care nu le cunoașteți; un parser care eșuează la un câmp necunoscut nu este conform.
fără schimbare — Un ANUNȚ de depreciere: înștiințarea că o comandă va dispărea — Codul dumneavoastră continuă să ruleze. Puneți o sarcină în calendar — fereastra este de cel puțin 6 luni.
crește — Eliminarea unei comenzi · retragerea unui nume CLI vechi · eliminarea unui câmp din răspuns · transformarea unui parametru opțional în obligatoriu · restrângerea unui enum — Înseamnă că ați ratat fereastra; înștiințarea a ajuns la dumneavoastră în trei locuri diferite.
Numele API al unei comenzi (cum ar fi list_loads) este înghețat pentru totdeauna; acesta este numele pe care îl folosiți în apelurile HTTP.
error_code (transport) și error_key (regulă de business) sunt șiruri stabile. Pot apărea unele noi — tratați o cheie pe care nu o găsiți în dicționar ca pe un eșec generic, nu ca pe o ruptură de compatibilitate.
Corespondența dintre statusul HTTP și câmpul status din corp este fixă.
Numărul versiunii nu scade niciodată și poate fi citit pe fiecare răspuns — inclusiv pe 304 și 429 fără corp.
TEXTUL erorilor și al descrierilor. Este localizat și se schimbă fără preaviz; ramificarea după textul mesajului nu este suportată.
Absența câmpurilor pe care nu le cunoașteți. Adăugarea unui câmp nu crește versiunea.
Id-urile auto-increment drept chei de business. Purtați propria cheie cu external_ref.
Cheile de eroare dinamice derivate din nume de clase; ele nu fac parte din contract.
Tabelul de identitate al comenzilor
Tabelul de mai jos nu este scris de mână: este generat din registrul live de comenzi de fiecare dată când această pagină este servită. O comandă adăugată pe server apare aici de la sine. Coloana „Poartă” vă spune dacă o comandă cere confirmare și dacă efectul ei poate fi anulat; coloana „Roluri” vă spune ce tipuri de cont o vor găsi în catalogul lor. Badge-urile marchează comenzile care necesită o cheie de nivel manager, pe cele care primesc un fișier și pe cele care rulează doar din lg.
Comenzile sunt grupate pe funcții, fiecare pe propria pagină. Alegeți o funcție pentru a deschide tabelul ei de comenzi.
Numele API (list_loads) este înghețat și nu se va schimba; este numele pe care îl folosiți în apelurile HTTP. Identitatea CLI (loads list) este guvernată de politica de versionare: odată anunțată, se schimbă doar cu o creștere de versiune și o fereastră de migrare, în care catalogul servește perechea veche ca alias. Descrierile de aici provin din înregistrarea proprie a fiecărei comenzi și sunt prescurtate — pentru textul complet, tipurile parametrilor și valorile enum, citiți endpoint-ul de catalog sau rulați lg help . Comenzile exclusive afiliaților nu sunt listate aici; un cont de afiliat le vede în propriul catalog.
Încărcături și urmărire — Crearea încărcăturilor, părți implicate, documente, linkuri de urmărire, semnătura la livrare, ETA și excepții. 115 comenzi — /ro/developers/cli/loads
Frontieră și vamă — Verificarea pregătirii pentru frontieră, așteptarea la frontiere și în porturi, documente de export, raportare U-ETDS. 42 comenzi — /ro/developers/cli/border
Cereri și oferte — Deschiderea cererilor de transport, solicitarea și depunerea ofertelor, licitații, transportatori din rețea. 42 comenzi — /ro/developers/cli/quotes
Liste de tarife și oferte de vânzare — Tarife negociate, cascada de oferte și ofertele de vânzare către clienți. 57 comenzi — /ro/developers/cli/pricing
Flotă și șoferi — Șoferi, vehicule, bonuri de cheltuieli, conturi de șofer, planificarea curselor și zilele Schengen. 115 comenzi — /ro/developers/cli/fleet
Depozit și stoc — Depozite, rezervări, programări la rampă, ecranul porții, produse, stoc și paleți. 69 comenzi — /ro/developers/cli/warehouse
Contabilitate și facturare — Facturi, verificarea facturilor de achiziție, Paraşüt, înregistrări contabile, încasări și plăți, marje. 95 comenzi — /ro/developers/cli/finance
Mesaje și e-mail — Conversații pe încărcătură, mesaje directe, ciorne și căsuțe de e-mail, notificări. 58 comenzi — /ro/developers/cli/messages
Tarif vamal și măsuri comerciale — Căutarea codurilor SA, taxe la import, măsuri antidumping, rapoarte de carbon. 20 comenzi — /ro/developers/cli/tariffs
Firme și echipă — Registrul de firme, relații și documente, filiale, colegi de echipă și invitații. 65 comenzi — /ro/developers/cli/contacts
Automatizare și rapoarte — Reguli de automatizare, rapoarte personalizate, fișiere Excel și PDF, planuri de lucru. 27 comenzi — /ro/developers/cli/automation
Cont și integrare — Setări de cont și limbă, chei de integrare, pachet, credite și portofel. 16 comenzi — /ro/developers/cli/account
Integrare ERP și CRM — Identitate: fără conturi de serviciu, în schimb un utilizator real
Un ERP sau un CRM se conectează la Logistivo ca un utilizator real al companiei, care deține un token de acces personal emis din panou. Un cont de serviciu sintetic — fără companie, scutit de delimitare, fără nimeni responsabil de el — nu este creat niciodată.
Aceasta este arhitectură, nu preferință. Izolarea multi-tenant se sprijină în întregime pe compania utilizatorului; pentru o identitate fără companie, domeniul de izolare devine inert, iar o singură interogare greșită pe acel token citește date care nu îi aparțin. Al doilea motiv este auditul: coloana de utilizator din registru leagă „cine a rulat asta” de o persoană; un cont de serviciu golește acea coloană de sens și lasă o integrare care emite facturi fără proprietar. Al treilea este revocarea: dacă un token aparține unei persoane, integrarea amuțește când acea persoană pleacă. Un bridge fără proprietar este bridge-ul care continuă să scrie discret ani de zile.
În practică: compania creează în panou un utilizator obișnuit (de exemplu „ERP Bridge”, deținut de un angajat anume), îi dă un rol restrâns, emite un token din sesiunea acelui utilizator și îl pune în ERP.
Acel utilizator este vizibil în sistemul de permisiuni, drepturile sale pot fi restrânse, iar token-ul său poate fi revocat separat. Ce este interzis nu este crearea unui cont — ci crearea unui cont care nu este legat de un tenant.
O integrare per token. Dacă două sisteme partajează un token, granularitatea revocării dispare: a tăia accesul CRM-ului înseamnă a-l tăia și pe al ERP-ului.
Integrare ERP și CRM — Versionare și depreciere
Răspunsul catalogului poartă un întreg contract_version; rândurile comenzilor poartă since, deprecated_at și replaced_by. Versiunea contractului crește doar la modificări care rup compatibilitatea.
Versiunea NU crește pentru: o comandă nouă, un parametru opțional nou, un câmp nou într-un răspuns. Un consumator trebuie să ignore câmpurile pe care nu le cunoaște; un client care dă eroare la un câmp necunoscut nu este conform.
Versiunea CREȘTE pentru: eliminarea sau redenumirea unei comenzi, eliminarea unui câmp din răspuns, transformarea unui parametru opțional în obligatoriu, restrângerea unui enum. Forma veche rămâne activă cel puțin două trimestre calendaristice (6 luni), cu deprecated_at și replaced_by.
Deprecierea este anunțată în catalog, nu doar într-un changelog. Deoarece clientul se construiește din catalog, o comandă cu deprecated_at setat afișează un avertisment fără nicio versiune nouă a clientului, iar integratorul îl vede în logurile sale.
Numele API este înghețat pentru totdeauna. Identitatea CLI (domeniu/verb) putea fi redefinită liber înainte de a fi anunțată; după anunț, se schimbă doar cu o creștere de versiune și o fereastră de migrare, în care perechea veche este servită ca alias.
În practică: răspunsul catalogului și antetul X-Contract-Version poartă versiunea; fiecare rând de comandă poartă since, deprecated_at, replaced_by și aliases (perechi vechi domeniu/verb). Apelarea unei comenzi depreciate funcționează în continuare și răspunde cu un antet X-Deprecated: name; deprecated_at=…; replaced_by=… plus un obiect deprecated în corp. ?domain= pe catalog rezolvă un domeniu alias vechi la comanda curentă.
Un client care înțelege versiunea 1 și întâlnește un număr mai mare ar trebui să înregistreze un avertisment și să continue; lg face exact acest lucru. Retragerile în vigoare sunt listate în promisiunea de stabilitate de mai sus.
Integrare ERP și CRM — Identificatori stabili: nu dați niciodată ERP-ului un id auto-increment drept cheie
Id-urile interne auto-increment sunt opace și delimitate per tenant: id-ul valid al altei companii vă returnează „nu a fost găsit”, nu date. Dar faptul că sunt opace nu le face chei de business. Ceea ce stochează un ERP în propria înregistrare trebuie să fie o cheie de business.
Încărcătură: code (codul clientului, de ex. FSK2158). loads get funcționează deja după cod.
Țară: ISO 3166-1 alpha-2. countries search returnează codul.
HS / tarif: codul însuși — nomenclatura este deja universală.
Factură: numărul facturii, odată emisă. O ciornă are doar un id de suprafață, iar un id de ciornă NU este o cheie de business — ERP-ul ar trebui să poarte propria referință și să nu persiste niciodată un id de ciornă.
Produs, depozit, contact: astăzi doar un id de suprafață. Regula pentru comenzile noi este explicită: orice comandă care returnează un id de suprafață returnează și cheia de business proprie a tenant-ului (SKU, cod, cod fiscal), astfel încât ERP-ul să poată face potrivirea pe partea sa.
Integrare ERP și CRM — Paginare, filtrare și sincronizare incrementală
Comenzile de listare primesc limit și returnează count. Pentru o sincronizare nocturnă, contractul se angajează la următoarele; o comandă de listare care le-a adoptat declară cursor și updated_since în JSON Schema sa, iar până atunci tratați-o ca pe o fereastră mică (plafon de 20 de rânduri, fără cursor).
Cerere: limit (1..plafonul per comandă) plus cursor (opac, doar înainte, semnat de server). offset NU se folosește — într-un tabel live, un offset se deplasează; o înregistrare inserată între două pagini face ERP-ul să sară un rând sau să-l numere de două ori, și o face în tăcere.
Răspuns: { count, total?, next_cursor|null }. count este numărul de rânduri din acest răspuns; când next_cursor este null, lista este completă. Transmiteți next_cursor înapoi neschimbat — nu este un număr de pagină și nu vă revine dumneavoastră să-l construiți.
Un cursor alterat sau străin este respins cu 422 invalid_request; un cursor este legat de compania care l-a primit și nu poate pagina datele altui tenant.
Filtrare: parametrii numiți din JSON Schema, combinați cu AND. Nu există un limbaj liber de interogare — un DSL ar fi o a doua suprafață de interogare pe care ar trebui să o apărăm.
Sincronizare incrementală: updated_since (ISO-8601, UTC) plus cursorul. Stocați cel mai nou updated_at pe care l-ați văzut și transmiteți-l înapoi la următoarea rulare; fără el, fiecare ERP preia totul din nou în fiecare oră.
Referință externă: comenzile de scriere acceptă external_ref (propria dumneavoastră cheie de document), unică per companie; o a doua creare cu același external_ref este respinsă în loc să fie duplicată, iar list/get îl returnează astfel încât să puteți potrivi înregistrările pe partea dumneavoastră.
Integrare ERP și CRM — Limite de rată
Cheia limitei este token-ul, nu IP-ul: un ERP vine din spatele unui singur NAT, iar o limită bazată pe IP ar număra o întreagă companie ca un singur utilizator. Două integrări cu două chei nu își consumă niciodată una alteia cota — al doilea motiv pentru „o integrare per cheie”.
Descoperire fără autentificare (public/cli/catalog): 30 pe minut. Este un dicționar, nu o sursă de date; citiți-l o dată când vă scrieți bridge-ul, niciodată într-o buclă de producție.
Endpoint-uri de catalog (GET common/commands, GET common/commands/{name}): 120 pe minut per token. Catalogul se schimbă rar și răspunde cu 304 la If-None-Match; nu îl preluați din nou înaintea fiecărei comenzi — lg îl păstrează în cache timp de o oră.
Comenzi de citire (POST common/commands/{name} cu read_only: true): 120 pe minut per token.
Comenzi de scriere (POST common/commands/{name} cu read_only: false; un nume necunoscut se contorizează tot aici): 30 pe minut per token. Scrierile au efecte secundare; o buclă scăpată de sub control este facturată.
Comenzi care consumă credite (credit_cost din rândul de catalog nu este zero — de exemplu tariffs inquiry și export-documents generate): limita reală o reprezintă CREDITELE, nu numărul de cereri. Un răspuns 200 poate să fi consumat un credit.
Plafoane zilnice per companie, partajate cu panoul: comenzile care trimit e-mail sau push către persoane din afara companiei dumneavoastră consumă din 300 de notificări de ieșire pe zi, iar pornirea urmăririi plătite a containerelor sau navelor din 100 pe zi. Peste plafon, o comandă răspunde cu DAILY_LIMIT_REACHED și retry_after; încărcările de fișiere au propriile plafoane (vedeți Comenzi care primesc fișiere).
429 poartă întotdeauna Retry-After și un corp { error_code: "rate_limited", retry_after, limit, bucket }; respectați-l în loc să inventați o întârziere fixă. Catalogul publică valorile curente sub rate_limits.
Integrare ERP și CRM — Lucruri pe care nu le vom face
Aceasta este adesea cea mai utilă parte a unui contract: a ști ce nu va sosi niciodată vă permite să proiectați ținând cont de asta.
Niciun cont de serviciu și nicio entitate (principal) care să nu fie legată de un tenant.
Nicio plată, niciun număr de card și niciun consimțământ legal prin API sau printr-un chat. Acești pași rămân în browserul persoanei; o comandă vă oferă linkul.
Nicio a doua cale: nu există acces direct la baza de date, nici acces shell și nici un endpoint de operații în masă care să ocolească punctul unic de aplicare. Poarta de rol, poarta de confirmare, idempotența și registrul de audit sunt aplicate doar acolo.
Ramificarea după textul mesajelor de eroare nu este suportată; textul este localizat și se schimbă fără preaviz.
Fără paginare cu offset.
Folosirea unui id de suprafață drept cheie de business în ERP-ul dumneavoastră nu este suportată.
Webhook-urile de ieșire nu sunt înghesuite în acest contract — dar acum EXISTĂ și sunt documentate pe această pagină (secțiunea despre webhook-uri de mai sus). Catalogul este o suprafață PULL, iar fluxul de evenimente este un contract SEPARAT: numele evenimentelor și schema payload-ului sunt versionate după propriile reguli și nu sunt legate de versiunea contractului catalogului de comenzi.
Catalogul lizibil automat
Această pagină a fost scrisă pentru oameni. Pentru un asistent AI sau un client automat, aceleași informații există ca o copie structurată, fără autentificare.
GET /api/public/cli/catalog nu necesită autentificare și returnează identitatea publică a comenzilor: numele API înghețat, identitatea CLI domeniu/verb, descrierea, parametrii JSON Schema, flag-urile read_only, confirmation_needed și irreversible, credit_cost și câmpurile de acces key_level, permission, file_params, secret_parameters și cli_only. Nu returnează date personale, date ale tenant-ilor sau înregistrări de exemplu — doar ce este suprafața.
Modul corect în care un agent extern îl poate folosi: citește catalogul, explică în PROPRIILE cuvinte ce operațiuni sunt posibile și, când este nevoie de execuție, îl îndrumă pe utilizator să o ruleze în propriul mediu, cu propriul token. Agentul nu cere, nu generează și nu transmite niciodată token-ul unui utilizator.
Conectarea Logistivo la un asistent AI pentru înscriere și cereri de transport este un canal separat, cu propria pagină:
Catalogul nu necesită autentificare; execuția, da. Nu există nicio modalitate de a rula o comandă în numele unui agent — ceea ce rulează este întotdeauna identitatea proprie a utilizatorului.
O parolă Logistivo, un cod de verificare sau un token de acces nu trec niciodată printr-un chat. Nu construiți un flux care cere, generează sau transmite așa ceva.
Dacă o comandă este ireversibilă scrie în catalog. Nu sugerați niciodată „hai să încercăm” pentru o comandă cu irreversible: true.
Comenzile al căror credit_cost nu este zero (de exemplu tariffs inquiry și export-documents generate) au un rezultat bănesc; nu le apelați într-o buclă automată.
Plățile, numerele de card și consimțământul legal nu trec niciodată printr-un chat sau printr-un agent. Oferiți în schimb linkul din handoff-links generate; persoana finalizează pasul în propriul browser.
Un agent care acționează cu cheia unui utilizator ar trebui să apeleze mai întâi users get: returnează rolul, nivelul de acces al cheii, permisiunile efective și dacă un consimțământ în așteptare sau o verificare a telefonului blochează scrierile — anticipați refuzurile în loc să le colecționați.
O versiune în text simplu a acestei pagini se află la /cli.md; folosiți-o dacă parsați markdown mai fiabil decât HTML.
Definiția lizibilă automat: OpenAPI 3.1 și Postman
Catalogul de mai sus este formatul propriu al Logistivo. Aceleași informații sunt publicate și în două formate standard din industrie pe care instrumentele dumneavoastră le înțeleg deja: o definiție OpenAPI 3.1 și o colecție Postman. Niciuna nu este scrisă de mână — ambele sunt generate din registrul live de comenzi la fiecare cerere, deci nu se pot învechi.
Definiția ESTE catalogul, nu o a doua realitate. Fiecare comandă apare ca o operațiune POST /api/common/commands/; schema corpului este propria JSON Schema a comenzii (octet cu octet ce vede asistentul), schema răspunsului este plicul comun, flag-urile de poartă (read_only, confirmation_needed, irreversible și badge-ul de credit) stau în extensia x-logistivo, iar cheile de eroare de business stau sub x-error-keys. O comandă retrasă este marcată deprecated: true și rămâne apelabilă pe durata ferestrei sale de șase luni.
Pe lângă suprafața de comenzi, în definiție se află și endpoint-urile REST care poartă contractul de integrare: 10 endpoint-uri de listare cu sincronizare incrementală (updated_since + cursor + limit) și 7 endpoint-uri de scriere care acceptă propria dumneavoastră cheie (external_ref). Suprafața REST a Logistivo este mult mai mare de atât; restul este lăsat deoparte INTENȚIONAT. Acele payload-uri sunt contractul propriu al produsului, iar o schemă scrisă din presupuneri v-ar strica clientul generat la primul apel — și ați căuta bug-ul în codul dumneavoastră, nu în al nostru.
Definiția este generată pentru ROLUL celui care o cere: comanda unui alt rol nu intră niciodată în document, pentru că o definiție este un contract, nu un dicționar, iar tot ce conține trebuie să fie apelabil cu acel token. Versiunea fără autentificare este reuniunea celor trei roluri și, acolo, fiecare operațiune indică sub x-logistivo.roles ce roluri o văd.
Nu ne credeți pe cuvânt — verificați: npx @redocly/cli lint logistivo-openapi.json trece cu zero avertismente.
GET /api/common/spec/openapi.json — Definiția OpenAPI 3.1 pentru rolul token-ului dumneavoastră. Poartă un ETag; If-None-Match vă dă un 304, astfel încât să nu o descărcați din nou la fiecare build.
GET /api/common/spec/postman.json — Același perimetru ca o colecție Postman v2.1, cu variabilele base_url și token și cu dosarele deja grupate pe domenii de comenzi.
GET /api/public/cli/openapi.json — Versiunea fără autentificare — reuniunea celor trei roluri. Pentru proiectarea și estimarea costului bridge-ului înainte de a avea un token.
GET /api/public/cli/postman.json — Colecția Postman fără autentificare: un singur fișier pe care îl puteți da echipei dumneavoastră.
761 de operațiuni — 721 de comenzi + 36 de operațiuni REST și de control + 4 endpoint-uri de catalog și de identitate. Cifrele de pe această pagină nu sunt tastate de mână; sunt numărate din documentul live la fiecare cerere, așa că în ziua în care se lansează o comandă cresc și aici — și se adună corect.
Schema de securitate — bearerAuth: un token Passport emis pentru un utilizator real. O cheie cu scope de citire poate apela doar operațiunile marcate x-logistivo.read_only: true; o încercare de scriere returnează 403 ÎNAINTE de poarta de confirmare, astfel încât o cheie doar de citire nu vede niciodată un 409.
Fiecare ramură de eroare este descrisă explicit — Fiecare operațiune descrie separat 401/403/404/409/422/429/500. Cele două sensuri ale lui 409 (confirmare necesară / conflict de idempotență) și cele două sensuri ale lui 422 (eroare de schemă / respingere de business) sunt distincte în document, astfel încât generatorul dumneavoastră nu le contopește într-o singură ramură.
Fără timestamp — Documentul nu conține momentul generării. Același catalog produce aceiași octeți, de aceea ETag-ul chiar funcționează, iar o definiție pe care o puneți în controlul versiunilor nu pare „modificată” la fiecare descărcare.
Nu am inventat payload-urile produsului — La endpoint-urile REST de scriere este descris doar câmpul de contract (external_ref); restul corpului rămâne deschis ca additionalProperties: true, iar cititorul este îndrumat spre documentația produsului. O definiție incompletă, dar adevărată, este mai bună decât una completă, dar inventată.
Lista cheilor de eroare per operațiune NU este exhaustivă — x-error-keys listează doar cheile care rezultă cu certitudine din înregistrarea proprie a comenzii și spune acest lucru prin x-error-keys-exhaustive: false. Dicționarul complet se află la rădăcina documentului; tratați orice cheie pe care nu o recunoașteți ca pe un eșec generic. O „listă completă” fabricată v-ar fi împins să nu scrieți niciodată ramura implicită.
Instrumentele de descoperire nu sunt în definiție — search_commands, run_command și list_capabilities există doar în bucla de chat și nu pot fi apelate prin HTTP. Dacă ar fi fost incluse, generatorul dumneavoastră ar fi scris trei metode care nu ar fi putut funcționa niciodată.
Generare de cod: un client tipizat din definiție
Aveți definiția; acum generați din ea cod funcțional. `lg codegen` citește documentul OpenAPI și scrie un client într-un singur fișier, fără dependențe — TypeScript (declarații de tipuri plus un wrapper subțire de apel) sau PHP (o clasă client cu forme de array PHPDoc). Fără `npm install`, fără composer: `fetch` pe partea TypeScript, `ext-curl` pe partea PHP.
Generarea are loc pe mașina DUMNEAVOASTRĂ, nu pe serverul nostru. Nu este o preferință: fixați definiția în repository-ul dumneavoastră o singură dată (`lg spec --out=...`), iar aceeași comandă rulează la fiecare build fără rețea și fără token, astfel încât CI-ul dumneavoastră nu depinde niciodată de disponibilitatea noastră. Și cum codul generat este cod care RULEAZĂ în ERP-ul dumneavoastră, păstrarea lui în repository în loc de a-l prelua dintr-un API înseamnă că fiecare schimbare apare în `git diff`.
Clientul generat tratează corect toate cele trei căi Logistivo și află care este care din document, nu prin ghicit: fiecare operațiune își declară calea în `x-logistivo.surface`. Calea de comenzi despachetează plicul `{success, data:{…}}`; o listă REST de sincronizare NU are plic și este returnată ca atare (despachetarea ar pierde `next_cursor`); o scriere REST returnează corpul propriu al endpoint-ului din produs. Un generator de uz general nu cunoaște această distincție — al nostru o cunoaște.
Tipurile nu sunt presupuneri: interfața de argumente a fiecărei comenzi este generată chiar din JSON Schema pe care o vede asistentul. Ce este obligatoriu rămâne obligatoriu, enum-urile devin tipuri union, obiectele imbricate devin tipuri imbricate. În practică: dacă serverul cere un câmp, apelul care îl uită nu eșuează cu un 422 în producție — eșuează la compilare.
În fișier nu se scrie niciun timestamp de generare: aceeași definiție cu aceleași flag-uri produce aceiași octeți. Prin urmare, regenerarea nu face zgomot în `git diff`, iar singurul lucru care s-a schimbat cu adevărat — contractul — rămâne vizibil.
1. Fixați definiția — Definiția este generată pentru rolul dumneavoastră; fiecare operațiune din ea este apelabilă cu acel token. Faceți commit fișierului. lg login --api-key= lg spec --out=logistivo-openapi.json
2. Generați clientul — Rezultă un singur fișier, care conține ca metodă FIECARE operațiune din definiția pe care ați fixat-o: comenzile pe care le poate apela rolul dumneavoastră, endpoint-urile REST care poartă contractul de integrare și endpoint-urile de descoperire. Numărul este cel al rolului DUMNEAVOASTRĂ, nu totalul platformei — astăzi o cheie de expeditor produce 646 de metode de comandă, una de transportator 621, una de comisionar vamal 392. Generați din definiția publică fără autentificare, iar plafonul este de 761 de operațiuni. 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. Verificați, apoi folosiți — Dacă codul generat nu se compilează, vina este a noastră, nu a dumneavoastră: integritatea definiției este păzită de o verificare executabilă pe server. npx tsc --noEmit --strict --target ES2022 --module ESNext --moduleResolution bundler logistivo-client.ts php -l LogistivoClient.php
O metodă pentru fiecare operațiune — Fiecare comandă din document, fiecare endpoint REST care poartă contractul de integrare și endpoint-urile de descoperire. Generați din definiția rolului dumneavoastră și primiți doar ce puteți apela (646 de comenzi pentru un expeditor); generați din definiția publică și primiți toate cele 761 de operațiuni. În ziua în care o comandă este adăugată pe server, regenerarea o aduce; nu trebuie să așteptați nicio versiune nouă a clientului.
Tipurile argumentelor — Schema `args` a fiecărei comenzi devine o interfață (o formă de array în PHP). Câmpurile obligatorii rămân obligatorii, enum-urile devin union-uri. În TypeScript, uitarea unui câmp obligatoriu este o eroare de compilare; în PHP, IDE-ul dumneavoastră și PHPStan văd aceeași formă.
Clase de erori — Taxonomia de transport (`error_code`) și taxonomia de business (`error_key`) sunt câmpuri separate; poarta de confirmare și limita de rată sunt tipuri de eroare separate. Union-ul cheilor de eroare rămâne deschis pentru valori necunoscute — când serverul declară o cheie nouă, codul dumneavoastră nu încetează să se compileze, ci ajunge în ramura `default`.
O politică de reîncercare corectă — Reîncercările automate se aplică doar apelurilor sigure: citirilor și scrierilor care poartă o cheie de idempotență. O scriere fără cheie care expiră nu înseamnă „nu s-a scris nimic”, așa că clientul nu o repetă niciodată orbește. La un 429 așteaptă `Retry-After` indicat de server în loc să inventeze o întârziere.
Corpurile rezultatelor nu sunt tipizate — Rezultatele comenzilor revin ca `unknown` (`mixed` în PHP), din același motiv ca în definiția însăși: formele rezultatelor sunt output-ul de business al comenzii, nu parte a contractului. Un tip de rezultat ghicit ar începe să mintă prima dată când un câmp se mută.
Fișierul generat nu se editează manual — Este un output, nu o sursă. Dacă aveți nevoie de comportament suplimentar, înfășurați clasa generată; orice scrieți în interiorul ei se pierde la următoarea generare.
Instrumentele de descoperire nu sunt generate — `search_commands`, `run_command` și `list_capabilities` trăiesc doar în bucla de chat și nu pot fi apelate prin HTTP; lipsesc din definiție și, prin urmare, din client. Includerea lor ar fi însemnat scrierea a trei metode care nu funcționează niciodată.
Perimetru onest
Am prefera să extindem această secțiune decât să o restrângem. Valoarea unui contract de integrare stă mai puțin în ceea ce promite și mai mult în cât de clar spune ce nu face.
CLI-ul rulează în contextul unui utilizator al tenant-ului — Fiecare comandă rulează sub compania și rolul utilizatorului al cărui token este prezentat. Un mod de operator al platformei — un mod administrativ care citește date din mai multe companii — se află în afara acestei suprafețe și nu va fi deschis de aici.
Lista dumneavoastră de comenzi depinde de rol — Un cont de expeditor vede 646 de comenzi, un transportator 621, un comisionar vamal 392, un afiliat 55. Dacă o comandă lipsește din catalogul dumneavoastră, verificați mai întâi rolul; dacă este listată, dar refuzată, verificați scope-ul și nivelul de acces al cheii. Conturile de șofer nu au deloc acces la această suprafață.
Unele comenzi consumă credite — Interogările de tarife, generarea de documente și alte câteva comenzi bazate pe AI consumă din soldul de credite al planului dumneavoastră. Fiecare rând din catalog poartă credit_cost {mode, credits}: fixed este taxa exactă per apel, read_only nu taxează niciodată, iar computed înseamnă că taxa depinde de apel — credits este atunci null, iar cifra reală apare pe cardul de confirmare. Un preflight (dry_run) vă spune cât ar costa un apel și dacă soldul îl acoperă.
Cheile de integrare nu pot conduce chatul din panoul de control — Asistentul AI din panoul de control este pentru oameni. Pornirea sau continuarea unei rulări a asistentului cu o cheie de integrare este refuzată cu 403; agenții folosesc endpoint-urile de comenzi, lg sau canalul MCP, unde fiecare comandă rulează la nivelul de acces al cheii, iar scrierile ei sunt înregistrate ca scrieri de integrare.
Catalogul nu înlocuiește API-ul REST existent — Suprafața REST care alimentează aplicațiile web și mobile Logistivo rămâne unde este și se află în continuare sub regula de compatibilitate înapoi. Catalogul de comenzi nu înlocuiește CRUD-ul pe resurse; el este stratul VERBELOR — modul unic, auditat, de a face un lucru.
Comenzile de listare returnează astăzi ferestre mici — Până când o comandă de listare nu declară cursor și updated_since în schema sa, plafonul ei este de 20 de rânduri, fără cursor. Nu este concepută pentru extragerea unei copii complete a datelor dumneavoastră; sincronizarea incrementală se implementează comandă cu comandă.
Întrebări frecvente
La ce folosește Logistivo CLI?
Execută munca din contul dumneavoastră Logistivo dintr-un terminal, dintr-un script sau din propriul agent AI: încărcături și curse, cereri de transport, oferte și licitații, flotă, șoferi și cheltuielile lor, documente, contacte și conturi curente, facturi și contabilitate, depozit și stoc, membri ai echipei, tarife HS și taxe antidumping. Fiecare acțiune de scriere din panou are o comandă; plățile, consimțământul legal și închiderea contului rămân în mod deliberat în browser. Aceleași comenzi pot fi apelate prin HTTP pentru integrări ERP/CRM și prin canalul MCP.
Cum sunt denumite comenzile în Logistivo CLI?
Forma este lg --parameter=value. Domeniul este o entitate la plural (loads, demands, invoices, export-documents), iar verbul provine dintr-un vocabular închis care crește doar prin decizie deliberată (list, get, create, update, search, set-status, generate și așa mai departe). Toate verbele unei entități stau într-un singur domeniu, iar perechea (domeniu, verb) este unică în întregul catalog.
Cum mă autentific în CLI?
Interactiv, lg login afișează un cod de aprobare pe care îl confirmați în browser după ce vă autentificați în Logistivo — în terminal nu se tastează nicio parolă și nicio cheie, iar sesiunea rămâne autentificată și se reînnoiește singură până când rulați lg logout. lg login --password (e-mail și parolă) rămâne ca variantă de rezervă. Pe servere și în CI, folosiți o cheie de integrare emisă în panou sau cu lg keys create: lg login --api-key o salvează într-un profil local, sau o puteți pune în variabila de mediu LOGISTIVO_TOKEN. Prin HTTP, token-ul călătorește în antetul Authorization: Bearer.
Pot crea un cont de serviciu pentru integrarea ERP?
Nu. O integrare se conectează cu token-ul unui utilizator real al companiei, creat în panou. O identitate sintetică fără companie face inertă izolarea multi-tenant, golește de sens coloana „cine a rulat asta” din registrul de audit și lasă în urmă un bridge care nu amuțește atunci când proprietarul său pleacă. Modelul corect este un utilizator dedicat, cu un rol restrâns și un proprietar numit.
Are Logistivo un mediu de test (sandbox)?
Da, și este self-service: pentru compania dumneavoastră se deschide un tenant sandbox separat — același cod, același catalog de comenzi, propriul registru de credite. Mediul este dedus din compania cheii și nu poate fi transmis odată cu cererea; un apel făcut cu profilul greșit se oprește pe server cu 403 ENVIRONMENT_MISMATCH. O cerere de transport deschisă în sandbox nu ajunge niciodată la transportatori reali, un eveniment din sandbox nu este livrat niciodată abonamentului dumneavoastră webhook live, iar soldul live nu se modifică. Endpoint-uri: POST /api/common/integration-sandbox (deschidere), POST /api/common/integration-sandbox/keys (cheie), GET /api/common/integration-sandbox/go-live (lista de verificare pentru go-live). Pe partea lg, lg --sandbox și lg --live sunt selectoare de profil pentru o singură rulare.
Cum citesc output-ul lg --json într-un script?
Output-ul este întregul plic HTTP: { "success": bool, "data": { "contract_version", "command", "status", "result" }, "code", "message" }. Payload-ul de business se află sub .data.result; la comenzile de listare, rândurile sunt .data.result., numărul este .data.result.count, iar pagina următoare este .data.result.next_cursor. Așadar, calea jq corectă arată astfel: lg loads list --json | jq -r '.data.result.loads[].load_code'. O cale care sare peste plic nu dă eroare, ci returnează în tăcere null — într-un script de supraveghere, asta devine o alarmă care nu se mai oprește. Singura excepție este /api/public/status, al cărui corp este în mod deliberat fără plic.
Dacă trimit aceeași cerere de două ori, obțin înregistrări duplicate?
Nu, dacă ați trimis un idempotency_key. Un al doilea apel cu aceeași cheie nu rulează din nou comanda; returnează primul rezultat cu statusul replayed. Cheia ar trebui să fie un UUID și trebuie să rămână ACEEAȘI între reîncercări — a genera o cheie nouă la fiecare încercare este totuna cu a nu folosi idempotența.
Ce face --yes?
Trece de poarta de confirmare. Când o comandă supusă confirmării este apelată fără --yes, nu se schimbă nimic: serverul rezumă într-o propoziție ce urmează să facă, spune dacă acțiunea este ireversibilă și se oprește (HTTP 409, cod de ieșire CLI 4). Repetarea comenzii cu --yes execută munca.
Cum detectez într-un script o comandă eșuată?
Citiți codul de ieșire, niciodată textul mesajului: 0 succes, 1 respingere de către o regulă de business, 2 eroare de comandă sau de argument, 3 eroare de autentificare sau de rol, 4 confirmare necesară. Prin HTTP, echivalentele sunt 200, 422, 404, 403 și 409, iar câmpul error_code din corp este stabil. MESAJUL de eroare este localizat și se schimbă fără preaviz.
Cum descopăr programatic comenzile disponibile?
GET /api/public/cli/catalog pentru descoperire fără autentificare și GET /api/common/commands pentru lista pe care contul dumneavoastră o poate vedea efectiv. Ambele returnează parametrii JSON Schema ai fiecărei comenzi; construiți-vă clientul pe baza lor, în loc să scrieți în cod o listă fixă de comenzi.
Trebuie să-mi actualizez clientul când se adaugă o comandă nouă?
Nu. Clientul își preia lista de comenzi din catalog, așa că o comandă adăugată pe server apare fără o versiune nouă a clientului. O actualizare este necesară doar pentru o modificare care rupe compatibilitatea și crește versiunea contractului, iar în acest caz forma veche rămâne activă cel puțin șase luni.
Înlocuiește CLI-ul API-ul REST existent?
Nu. Suprafața REST care alimentează aplicațiile web și mobile rămâne pe loc. Catalogul de comenzi nu înlocuiește CRUD-ul pe resurse; el este stratul verbelor — modul unic de a efectua o acțiune, protejat de poarta de rol și de poarta de confirmare și auditat.
Cum obțin o cheie API Logistivo și ce poate face?
Un manager cu permisiunea de gestionare a echipei o emite în panou, la Settings › Integration keys, sau dintr-un terminal cu lg keys create. Cheia acționează în numele unui membru real al echipei și are trei setări independente: scope-ul (read deschide catalogul și comenzile care nu scriu, write deschide orice comandă — poarta de confirmare rămâne așa cum este), permisiuni opționale pe domenii și un nivel de acces — employee, implicit, pentru operațiunile de zi cu zi, sau manager pentru echipă, setări, chei și bani. Este afișată o singură dată și nu este stocată pe server; poate fi rotită, transferată și revocată. Când membrul în numele căruia acționează pleacă, cheia se închide și ea. Nu există cont de serviciu.
Ce se întâmplă dacă refolosesc o cheie de idempotență pentru o altă comandă?
Serverul răspunde cu 409 idempotency_conflict și numește comanda pentru care a fost folosită prima dată cheia; nu rulează nimic și nu se reia nimic. Cheile sunt limitate la compania dumneavoastră, legate de o singură comandă și blocate timp de 24 de ore — după aceea, aceeași cheie pornește o execuție nouă.
Cum se aplică limitele de rată integrării mele?
Per token, pe minut, în trei categorii: citiri de catalog 120, comenzi de citire 120, comenzi de scriere 30. Un 429 poartă întotdeauna Retry-After și un corp cu retry_after, limit și bucket; așteptați atât și reîncercați. Catalogul publică valorile curente sub rate_limits.
Cum deosebesc o respingere de business de o eroare de transport?
Ramificați mai întâi după error_code: failed (422) este o respingere de business și poartă un error_key stabil, precum INSUFFICIENT_CREDITS sau NOT_FOUND; server_error (5xx) și erorile de rețea se reîncearcă cu aceeași cheie de idempotență; la rate_limited (429) se așteaptă. Nu ramificați niciodată după textul erorii.
Trimite Logistivo webhook-uri? Pentru ce evenimente?
Da. Înregistrați o adresă https și alegeți evenimentele care vă interesează; un POST semnat sosește atunci când acestea au loc. Astăzi vă puteți abona la 13 evenimente: încărcătură creată/status schimbat/șofer alocat, cerere de transport creată și status schimbat, ofertă plasată/revizuită/acceptată, factură ciornă/emisă/anulată și rezervare de depozit creată/status schimbat. Fiecare nume este susținut de o clasă de eveniment care este emisă efectiv — nimic nu este anunțat și apoi niciodată declanșat, pentru că un astfel de eveniment este un eșec tăcut pe care integratorul îl așteaptă la nesfârșit. Abonamentele se creează la Settings › Integration › Webhooks sau dintr-un terminal cu lg webhooks create.
Cum verific semnătura unui webhook Logistivo?
Fiecare cerere poartă un antet X-Logistivo-Signature: t=,v1=. Șirul semnat este ".", algoritmul este HMAC-SHA256, iar cheia este secretul abonamentului. Patru reguli: (1) verificați octeții BRUȚI — decodarea și reserializarea corpului (JSON.stringify / json_encode) transformă aceleași date în octeți diferiți, iar semnătura nu se mai potrivește; aceasta este cea mai frecventă greșeală; (2) verificați timestamp-ul și respingeți orice cerere pentru care |now − t| > 300 s, chiar dacă semnătura este corectă; (3) comparați în timp constant cu hash_equals / timingSafeEqual; (4) deduplicați după event_id, nu după id-ul livrării — event_id se păstrează la reluare, în timp ce id-ul livrării se schimbă. Receptoare funcționale pentru Node și PHP se află în examples/webhook-receiver/ din repository și se testează singure cu --selftest.
Ce se întâmplă dacă un webhook nu poate fi livrat? Pierd evenimentul?
Nu. Dacă receptorul dumneavoastră nu returnează 2xx, livrarea intră în programul de reîncercări: intervale (în secunde) 60 · 300 · 1800 · 7200 · 21600, 6 încercări în total, o fereastră de aproximativ 8,6 ore. FIECARE eșec, cu excepția 410 Gone, este reîncercat, inclusiv 4xx — pierderea unui eveniment de business costă mai mult decât câteva cereri în plus. După 10 livrări consecutive epuizate, abonamentul este dezactivat, iar motivul este înregistrat, astfel încât întrebarea „de ce nu sosește nimic” rămâne cu răspuns. Registrul de livrări păstrează fiecare încercare (cod de status, durată, eroare), iar o livrare individuală poate fi retrimisă din panou sau cu lg webhooks replay. Sincronizarea incrementală (updated_since + cursor) rămâne în continuare plasa de siguranță.
Poate agentul meu AI să facă tot ce poate face un utilizator în panou?
Aproape tot. Fiecare acțiune de scriere din panou are o comandă — măsurat față de endpoint-urile de scriere ale panoului, 100% dintre cele aflate în perimetru sunt acoperite — iar aceleași comenzi sunt deschise pentru lg, pentru HTTP și pentru canalul MCP. Excepțiile deliberate sunt pașii legați de identitate și de bani: autentificarea, cumpărarea unui pachet, adăugarea unui card cu 3D Secure, aprobarea textelor legale și închiderea unui cont rămân în browserul persoanei, iar lg handoff-links generate returnează linkul pentru ele. Cheile de integrare, webhook-urile și sandbox-ul se gestionează cu comenzi încorporate în lg, pentru că returnează secrete o singură dată.
Pot transmite comenzilor fișiere, cum ar fi PDF-uri sau fotografii, din CLI sau din API?
Da. Cu lg, puneți @ în fața unei căi locale (--attachment_uuid=@./cmr.pdf), iar lg încarcă mai întâi fișierul; --file este o scurtătură atunci când o comandă are un singur câmp de fișier, iar lg upload doar încarcă. Prin HTTP, trimiteți fișierul ca multipart la POST /api/common/commands:upload și transmiteți comenzii attachment_uuid returnat; clienții MCP folosesc instrumentul upload_attachment. Tipul este detectat din conținut, încărcările aparțin utilizatorului și rămân utilizabile 24 de ore, iar încărcarea din nou a aceluiași fișier returnează același id.
Care este diferența dintre o cheie de integrare employee și una manager?
Nivelul de acces decide cât de grea poate fi munca pe care o face o cheie. O cheie employee, implicită pentru cheile noi, rulează operațiunile de zi cu zi: încărcături, cereri de transport, oferte, curse, flotă, documente și contacte. O cheie manager poate face și muncă de management — membri ai echipei și roluri, setările companiei, chei de integrare, conturi bancare, carduri salvate, plăți către afiliați. O cheie nu are niciodată mai multe drepturi decât persoana în numele căreia acționează, iar o cheie employee care apelează o comandă de manager primește INSUFFICIENT_KEY_LEVEL. Schimbați nivelul în panou sau cu lg keys update --access-level=manager.
Poate un afiliat (partener de recomandare) să folosească CLI-ul?
Da. Un cont de afiliat primește un catalog propriu — 55 de comenzi pentru recomandări, lead-uri, note și sarcini CRM, prezentări de vânzare, câștiguri și plăți — și îl folosește din lg, prin HTTP sau prin MCP, ca orice alt rol. Solicitarea sau anularea unei plăți și schimbarea contului bancar pentru plăți necesită o cheie de nivel manager și o confirmare. O companie care este și expeditor, transportator sau comisionar vamal vede ambele cataloage.
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.