Logistivo CLI: stuur je logistieke operatie aan vanuit een terminal en vanuit je ERP
Eén commandocatalogus voedt drie oppervlakken: de lg-terminalclient, de AI-assistent in het dashboard en het kanaal waarmee externe AI-assistenten verbinding maken. Een functie wordt één keer geschreven en verschijnt in alle drie — en elke schrijfactie in het paneel heeft nu een commando, zodat je scripts en je eigen AI-agents het werk kunnen doen dat je team op het scherm doet. Betalingen, juridische toestemming en het sluiten van een account blijven bewust in de browser. Deze pagina is een contract. De commandotabel hieronder is niet met de hand geschreven; ze wordt bij elk verzoek gegenereerd uit het live commandoregister.
Wat is de Logistivo CLI?
De Logistivo CLI (lg) is een opdrachtregelclient die het werk in je Logistivo-account uitvoert — ladingen en ritten, aanvragen, biedingen en tenders, wagenpark en chauffeurs, documenten, contacten en rekeningen-courant, facturen en boekhouding, magazijn en voorraad, teamleden en douanetarieven — vanuit een terminal, een script of je eigen AI-agent. De commando's zitten niet in de client ingebakken: de client haalt de commandocatalogus op van de server en bouwt zichzelf daaruit op. Dezelfde commando's zijn via HTTP aan te roepen zonder iets te installeren — dat is de route die ERP- en CRM-integraties gebruiken — en via het MCP-kanaal waarmee externe AI-assistenten verbinding maken.
Eén commandovorm: lg --parameter=value. De catalogus bevat vandaag 721 commando's in 175 domeinen; de breedste lijst die één rol ziet, telt 646 commando's in 165 domeinen.
Elke schrijfactie in het paneel heeft een commando — gemeten tegen de schrijf-endpoints van het paneel is 100% van de endpoints binnen de scope gedekt. Betalingen (3D Secure), juridische toestemming en het sluiten van een account blijven bewust in de browser; daarvoor geeft een commando in plaats daarvan een link terug.
Commando's die een document of foto aannemen, werken ook buiten de browser: schrijf --attachment_uuid=@./cmr.pdf en lg uploadt het bestand eerst; via HTTP upload je naar /api/common/commands:upload en geef je de teruggegeven attachment_uuid door.
Integratiesleutels hebben een toegangsniveau: employee (de standaard voor nieuwe sleutels) voor dagelijkse operaties, manager voor team, instellingen, sleutels en geld. Een sleutel heeft nooit meer rechten dan de persoon namens wie hij handelt.
Vlaggen worden nooit verzonnen: elke vlag is een parameternaam uit het eigen JSON Schema van het commando, en hetzelfde geldt voor het type en voor de vraag of de parameter verplicht is.
Schrijvende commando's vragen om bevestiging; onomkeerbare commando's draaien nooit zonder (HTTP 409, CLI-exitcode 4).
Opnieuw proberen levert geen duplicaten op: een aanroep met een idempotency_key wordt hoogstens één keer uitgevoerd.
Elke uitvoering komt in één auditlogboek terecht — of ze uit een terminal, uit de chat of van een assistent kwam, staat vastgelegd.
Wat er vandaag live is, en wat eraan komt
Deze sectie staat met opzet bovenaan de pagina. De duurste fout die een integratiedocument kan maken, is een endpoint dat nog niet open is beschrijven alsof het dat wel is: de integrator schrijft de code, het endpoint geeft 404 terug, en het vertrouwen komt niet meer terug.
Omdat het contract bevroren is, blijft de integratiecode die je vandaag schrijft werken terwijl de resterende onderdelen opengaan. Velden die je niet kent, moeten worden genegeerd; die regel is wat ons in staat stelt toe te voegen zonder iets te breken.
Commandocatalogus en identiteitstabel — De publieke domain/verb-identiteit van elk commando is bevroren en de contractversie wordt als 1 gepubliceerd in elk catalogusantwoord en in de header X-Contract-Version. De tabel op deze pagina wordt gegenereerd uit het live register: een commando dat op de server wordt toegevoegd, verschijnt hier vanzelf, en een verwijderd commando verdwijnt.
Discovery-endpoint zonder authenticatie — GET /api/public/cli/catalog — commandonamen, domain/verb-identiteit, beschrijving, JSON Schema-parameters, poortvlaggen en de versievelden (since, deprecated_at, replaced_by, aliases). Geen authenticatie: een token aanmaken is een stap die NA de integratiebeslissing komt, niet ervoor. Het antwoord bevat helemaal geen tenantgegevens.
Geauthenticeerde catalogus- en uitvoeringsendpoints — GET /api/common/commands, GET /api/common/commands/{name} en POST /api/common/commands/{name}. De rolcontrole, de bevestigingspoort, idempotency en het auditlogboek zitten op één enkel handhavingspunt waar ook de chat en de terminal doorheen gaan.
Paneeldekking: elke schrijfactie heeft een commando — 721 commando's in 175 domeinen, gecontroleerd tegen de schrijf-endpoints van het paneel: elk endpoint binnen de scope wordt gedekt door een commando (een spiegel van het endpoint of dezelfde gedeelde service), en geen enkel is onbewezen. Bewust buiten de scope: betalingen met 3D Secure, juridische toestemming, het sluiten van een account en inloggen, die in de browser blijven; het beheer van sleutels, webhooks en de sandbox, wat ingebouwde lg-commando's zijn; en de eigen endpoints van de chauffeursapp.
Preflight (dry_run): zien zonder uit te voeren — Met dry_run: true in de request body wordt het commando niet uitgevoerd: validatie, de rol-/scopecontrole, doelresolutie en de creditberekening draaien allemaal en er komt een preview terug; er wordt niets geschreven, er worden geen credits verbruikt en de idempotency key wordt niet opgebruikt. Ook het batch-endpoint accepteert het, per batch. Een preflight komt nooit in de handler van het commando; bij de lancering leverden 178 preflights over alle schrijfcommando's die toen in de catalogus stonden geen enkel schrijfstatement op.
Integratiesleutels — API-sleutels die namens een echt teamlid handelen, uitgegeven in het paneel of met lg keys create: lees-/schrijfscope, een toegangsniveau (standaard employee, of manager), looptijd, laatste gebruik, roteren, overdragen en intrekken. lg login --api-key, lg whoami en een lg logout die ook aan de serverkant intrekt, zijn daarop gebouwd.
Sandbox — schrijfacties oefenen zonder productie aan te raken — Een aparte sandbox-tenant per bedrijf met dezelfde commandocatalogus; je opent hem zelf (selfservice) en hij geeft zijn eigen sleutel uit. Credits, de marketplace en de webhook-routering zijn gescheiden tussen de twee omgevingen; de omgeving wordt afgeleid van het bedrijf van de sleutel en kan niet met het verzoek worden meegegeven.
Versiebeheer, fouttaxonomie, idempotency en rate limits — Commando's dragen since / deprecated_at / replaced_by / aliases en een verouderd commando antwoordt met een header X-Deprecated. Zakelijke fouten dragen een stabiele error_key naast de error_code op transportniveau, en het woordenboek met sleutels wordt in de catalogus gepubliceerd. Idempotency keys zijn beperkt tot je bedrijf, gebonden aan één commando en 24 uur vergrendeld. Rate limits gelden per token, in drie buckets, en elke 429 bevat Retry-After.
Uitgaande webhooks: een POST wanneer er iets gebeurt — Ondertekende push is live voor 13 events. Abonnementen worden beheerd vanuit het paneel of met lg webhooks; de handtekening draagt haar eigen tijdstempel, het retryschema is 60 · 300 · 1800 · 7200 · 21600 seconden en de reden van stillegging wordt altijd vastgelegd. Elke eventnaam wordt gedekt door een eventklasse die daadwerkelijk wordt verzonden — niets wordt aangekondigd en daarna nooit verstuurd. Het pull-spoor (updated_since + cursor) is niet verwijderd: push is ernaast toegevoegd, niet in plaats ervan.
Commando's die bestanden aannemen — 38 commando's nemen een document of foto aan — een CMR, een factuur, een kentekenbewijs, palletfoto's. Upload één keer naar POST /api/common/commands:upload, of laat lg het doen met --attachment_uuid=@./file.pdf, en geef de teruggegeven attachment_uuid door; MCP-clients gebruiken de tool upload_attachment. Het bestandstype wordt uit de inhoud bepaald, en een upload blijft 24 uur bruikbaar.
De lg-terminalclient — Gepubliceerd op npm onder de MIT-licentie: installeer met `npm install -g @lgstv/lg`, of draai hem zonder installatie via `npx @lgstv/lg`. Het is één enkel bestand zonder afhankelijkheden, en omdat het HTTP-oppervlak open is, kun je ook zonder de client integreren. Hij logt in met een goedkeuringscode die je in de browser bevestigt en blijft daarna ingelogd, waarbij hij zijn sessie zelf vernieuwt; hij uploadt lokale bestanden voor je (@path, --file, lg upload), beheert integratiesleutels (lg keys), neemt nooit een geheim aan op de opdrachtregel, respecteert Retry-After, probeert 5xx opnieuw met dezelfde idempotency key en waarschuwt bij verouderde commando's en nieuwere contractversies.
Incrementele sync: cursorpaginering en updated_since — Het contract hieronder (limit + ondoorzichtige, ondertekende cursor, next_cursor, updated_since) ligt vast en wordt uitgerold over de lijstcommando's. Zolang een bepaald lijstcommando cursor en updated_since niet in zijn JSON Schema aankondigt, behandel je het als een klein venster: maximaal 20 rijen, geen cursor.
Wat dit anders maakt: de client kent geen commando's, hij bouwt ze op
Dit is de ene beslissing die de rest van de pagina betekenis geeft. In een gewone CLI wonen de commando's in de client; bij Logistivo wonen ze op de server.
In de klassieke opzet heeft de client, wanneer de server een nieuwe functie krijgt, een nieuwe release nodig en moet de gebruiker die installeren. In de tussentijd weten de twee kanten verschillende dingen — en dat is de stilste faalwijze bij integraties: het script draait, de exitcode is 0, en het commando beschrijft gewoon niet wat de server kan.
Bij Logistivo is de definitie van een commando één enkel record: de naam, wat het doet, de JSON Schema-parameters, welke rollen het mogen zien, of het bevestiging nodig heeft en of het effect omkeerbaar is. Wanneer lg start, haalt het die catalogus op en genereert het daaruit de helptekst, de vlaggen en de invoervalidatie. Zodra er op de server een commando wordt toegevoegd, kent lg het — zonder client-update.
Dezelfde catalogus voedt de AI-assistent in het dashboard en het kanaal waarmee externe AI-assistenten verbinding maken. Een functie wordt één keer geschreven en verschijnt op drie plekken — en alle drie gaan door dezelfde rolcontrole, dezelfde bevestigingspoort en hetzelfde auditlogboek. Er is geen aparte inventaris van CLI-commando's; als die er was, zouden de drie oppervlakken binnen zes maanden ongemerkt uit elkaar groeien.
Geen versiedrift — De commandolijst die de client kent, is per constructie de lijst die de server heeft. "In welke lg-versie zit dit commando?" is een vraag die niet bestaat.
Vlagnamen worden nooit geraden — De vlaggen van een commando zijn precies de parameternamen in zijn JSON Schema. Je leert wat een commando accepteert niet door een document te lezen, maar door de catalogus te lezen — en de catalogus is altijd actueel.
Je CLI is zo groot als je account — De catalogus wordt per rol gefilterd: een commando dat je rol niet kan zien, verschijnt nooit in je lijst. Een vervoerdersaccount ziet 621 commando's, een verlader 646, een douane-expediteur 392, en een affiliate-account (doorverwijspartner) een eigen set van 55 commando's.
De documentatie kan niet achterlopen — De commandotabel op deze pagina komt uit hetzelfde register. Er bestaat nergens een lijst die een mens synchroon moet houden met de werkelijkheid.
De naamgevingsregel — hoe commandonamen groeien
De catalogus zal groeien. Nieuwe commando's krijgen geen naam op goed geluk; er worden zes regels toegepast. We publiceren ze hier omdat dit de namen zijn die je integratie jarenlang zal schrijven, en hun voorspelbaarheid is iets waard voor je.
Een domein is een entiteit in het meervoud — loads, demands, invoices, export-documents. Domeinen van twee woorden zijn kebab-case. De enige uitzondering is een ontelbaar zelfstandig naamwoord: stock wordt nooit in het meervoud gezet, omdat "stocks" iets anders betekent.
Alle werkwoorden van één entiteit wonen in één domein — loads bevat elk werkwoord dat op een lading werkt: create, list, get, update, set-status, assign-driver, list-problems, archive en meer. Per werkwoord een nieuw domein openen (load-statuses, load-drivers) zou een gebruiker op drie plekken naar dezelfde entiteit laten zoeken.
Het werkwoord lekt nooit in het domein; het domein is wat er VERANDERT — Een chauffeur toewijzen verandert de lading, niet de chauffeur, dus het is lg loads assign-driver. Het meewerkend voorwerp (-driver) hangt aan het werkwoord, nooit aan het domein.
Een subresource krijgt nooit een eigen domein — Een factuurregel en een documentitem kun je niet zelfstandig opsommen; ze worden via hun eigenaar aangesproken — lg invoices add-line, lg export-documents add-item. Eén test beslist: als je het ding niet zelfstandig kunt opsommen (list) of ophalen (get), is het geen domein.
Vernauwen is een vlag, geen nieuw werkwoord — lg fleet-documents list --days=30 is correct; er is geen apart werkwoord "list-expiring", omdat het venster al een parameter is. Een samengesteld werkwoord wordt alleen gebruikt wanneer de rijen die het teruggeeft niet de domeinentiteit zijn: loads list-problems geeft probleemmeldingen terug, geen ladingen.
Het paar (domein, werkwoord) is uniek in de hele catalogus — Zelfs voor twee commando's waarvan de rollen nooit overlappen. Als hetzelfde paar aan twee commando's werd gegeven, zou je integratiecode naar één naam kijken terwijl de CLI verschillende dingen uitvoerde, afhankelijk van wie hem aanriep.
Dekking: alles in het paneel, vanuit een commando
Veel teams koppelen Logistivo aan hun eigen AI-agent of automatiseringsharnas, en een agent is alleen nuttig als hij het werk kan afmaken. Daarom is de regel eenvoudig: wat een kantoorgebruiker in het paneel kan wijzigen, kan een commando ook wijzigen — achter dezelfde rolcontrole, dezelfde bevestigingspoort en hetzelfde auditlogboek.
Dit is gemeten, niet beweerd. Elk schrijf-endpoint achter het paneel wordt gecontroleerd tegen het commandoregister, en een endpoint telt alleen als gedekt wanneer een commando het als zijn HTTP-spiegel declareert of dezelfde gedeelde service aanroept. Van de schrijf-endpoints binnen de scope is 100% gedekt en geen enkel onbewezen. Elk weggelaten endpoint heeft een schriftelijke reden — stappen rond identiteit en betaling, het control plane van de integratie, de eigen endpoints van de chauffeursapp, clienttelemetrie, dode kopieën zonder aanroeper — en de endpoints die voor een integrator van belang zijn, staan hieronder.
Commando's die een bestand aannemen, vallen onder dezelfde regel: 38 commando's in de tabel nemen een document of foto aan, en ze werken allemaal vanuit lg, via HTTP en via MCP (zie Commando's die bestanden aannemen).
Ook beheerwerk is gedekt, achter een sterkere sleutel: 87 commando's in de tabel — teamleden en rollen, bedrijfsinstellingen, bankrekeningen, opgeslagen kaarten, integratiesleutels — vereisen een integratiesleutel op managerniveau. Een sleutel op employee-niveau, de standaard, voert dagelijkse operaties uit en wordt bij die commando's geweigerd met INSUFFICIENT_KEY_LEVEL.
Affiliate-accounts (doorverwijspartners) hebben een eigen catalogus: 55 commando's in 20 domeinen — doorverwijzingen, leads, CRM-notities en -taken, salespresentaties, verdiensten en uitbetalingen, plus de account- en teamcommando's die elke rol heeft. De commando's die alleen voor affiliates zijn, staan niet in de publieke tabel hieronder, die de drie paneelrollen toont; een affiliate-account ziet ze in GET /api/common/commands en in lg commands. Een bedrijf dat zowel affiliate als verlader, vervoerder of douane-expediteur is, ziet beide sets.
Een agent moet beginnen met lg users get (API-naam get_current_user): dat geeft de rol, het toegangsniveau van de gebruikte sleutel, de effectieve rechten en of een openstaande juridische goedkeuring of een niet-geverifieerd telefoonnummer op dit moment schrijfacties blokkeert — zodat de agent een weigering kan voorspellen in plaats van haar te verzamelen.
Dekking wordt gemeten met een rapport dat het commandoregister vergelijkt met de schrijf-endpoints van het paneel; een paneel-endpoint dat zonder commando wordt toegevoegd, verschijnt daarin als onbewezen. Vind je een actie in het paneel die je niet vanuit een commando kunt bereiken, meld die dan bij support.
1. Vraag om de link — Werk dat in de eigen browsersessie van de persoon moet gebeuren, is geen commando, maar het commando-oppervlak weet ervan. lg handoff-links generate (API-naam get_browser_handoff_link) geeft een logistivo.com-link terug voor de doelen die je rol toestaat: package_purchase, payment_cards, legal_documents, integration_keys, affiliate_demo_accounts en account_close. Het is gratis, schrijft niets, en de link bevat geen geheim — de persoon logt zoals gewoonlijk in.
2. Geef hem aan de persoon — Toon de link aan de gebruiker of stuur hem via je eigen kanaal. De persoon rondt de stap daar af: de contractgoedkeuring en de 3D Secure-betaling voor een pakket, een kaart toevoegen, openstaande juridische teksten goedkeuren, een API-sleutel uitgeven waarvan het geheim één keer wordt getoond, of het eigen account sluiten.
3. Lees de uitkomst met een commando — Zodra de stap is afgerond, is het resultaat weer zichtbaar voor commando's: het pakket en het creditsaldo, de opgeslagen kaart (gemaskeerd, alleen de laatste vier cijfers), de nieuwe sleutel in de sleutellijst. Een agent neemt nooit een kaartnummer, een betaling of een toestemming aan in een chat.
Betalingen en 3D Secure — Een pakket kopen of upgraden en een kaart toevoegen vereisen 3D Secure in de browser. Commando's tonen pakketten en prijzen, lezen het saldo en de geschiedenis ervan, tonen opgeslagen kaarten (gemaskeerd), stellen de standaardkaart in en verwijderen er een; de aankoop zelf loopt via de overdrachtslink.
Juridische toestemming — Juridische teksten goedkeuren doet de persoon zelf, in de browser. lg users get vertelt je dat er een goedkeuring openstaat; geen enkel commando kan die geven.
Account sluiten, inloggen en wachtwoord — Je eigen account sluiten, inloggen en een wachtwoord wijzigen zijn identiteitsstappen en blijven in de browser. lg user-accounts preview laat zien wat het sluiten van het account zou betekenen, zonder het te doen.
Integratiesleutels, webhooks en de sandbox — Het beheer ervan geeft geheimen terug die één keer, in je terminal, moeten worden getoond, dus het zijn ingebouwde lg-commando's (lg keys, lg webhooks, lg sandbox) op hun eigen HTTP-endpoints in plaats van catalogus-commando's. De catalogus bevat alleen de twee sleutelcommando's zonder geheim: integration-keys list en integration-keys revoke.
De assistentchat in het dashboard — Integratiesleutels kunnen de chat met de AI-assistent in het dashboard niet aansturen; een run starten of voortzetten met een sleutel geeft 403. Een agent maakt in plaats daarvan verbinding via de commando-endpoints, lg of het MCP-kanaal — daar draait elk commando op het toegangsniveau van de sleutel en worden de schrijfacties als integratieschrijfacties vastgelegd.
De chauffeursapp — Chauffeursaccounts hebben geen commandocatalogus, en de chauffeursapp houdt haar eigen endpoints. Kantoorgebruikers beheren chauffeurs, hun documenten, onkosten en ritten via commando's.
Installatie en identiteit
lg is een Node-script van één bestand zonder afhankelijkheden (Node 18+), gepubliceerd op npm als @lgstv/lg. Het pakket installeert twee identieke commando's, lg en logistivo — gebruik logistivo als lg op je machine al een alias is. Omdat het één bestand is, werkt het ook om lg.mjs naar de ERP-server van een klant te kopiëren. Je hebt de client niet nodig om een ERP/CRM-integratie te bouwen — dezelfde commando's zijn beschikbaar via HTTP.
1. Installeren — Node 18 of nieuwer is alles wat je nodig hebt; er zijn geen andere afhankelijkheden. Installeer het globaal of draai het zonder installatie via npx.
2. Inloggen met een goedkeuringscode — lg login toont een korte goedkeuringscode en opent logistivo.com/connect in je browser; via SSH, in CI of met --no-browser drukt het alleen het adres af, dat je op elk apparaat kunt openen, ook op je telefoon. Log daar zoals gewoonlijk in, controleer of de code op de pagina dezelfde is als die in je terminal, kies toegang voor alleen lezen of voor lezen en handelen, en keur goed. Er wordt niets geheims in de terminal getypt: geen wachtwoord, geen sleutel, geen eenmalige code. De sessie blijft daarna op die computer ingelogd — de terminal sluiten logt je niet uit, en lg vernieuwt het access token zelf voordat het verloopt. lg logout beëindigt de sessie ook op de server, en je kunt haar in het paneel verwijderen onder Settings › Integration keys › AI and CLI connections. lg login --password (e-mailadres en wachtwoord) blijft beschikbaar als terugvaloptie. Vereist lg 0.11 of nieuwer.
3. Voor servers en CI: een sleutel, geen goedkeuringscode — Op een server of in een CI-job is er niemand die een code in een browser kan goedkeuren. Geef een sleutel uit in het paneel (Settings › Integration keys) of met lg keys create — eventueel namens een speciaal daarvoor bestemd teamlid met beperkte rechten — en zet hem in LOGISTIVO_TOKEN, of sla hem op met lg login --api-key. Zolang de variabele is gezet, wordt het configuratiebestand nooit gelezen. Details: de sectie "Verbinden met een API-sleutel".
4. Controleren en de catalogus verkennen — lg commands toont elk commando dat je rol kan zien, gegroepeerd per domein; lg help toont de werkwoorden van dat domein, en lg help toont de volledige parameterlijst van één commando met de types en welke parameters verplicht zijn. Geen van die teksten zit in de client — alles komt uit de catalogus. Onthoud dat de lijst afhangt van je rol: de werkwoorden van één domein zijn niet dezelfde voor een vervoerder en voor een verlader (loads set-status staat bijvoorbeeld alleen in de vervoerderscatalogus). Ontbreekt er een werkwoord, controleer dan eerst je rol voordat je je installatie controleert.
Zet de sleutel nooit in versiebeheer, een CI-log of een chatvenster. Als je met een goedkeuringscode of een integratiesleutel bent ingelogd, beëindigt lg logout de sessie ook op de server; in een wachtwoordsessie (lg login --password) verwijdert het alleen de LOKALE kopie en zegt het dat ook expliciet. Het auditlogboek slaat je argumenten op, maar maskeert elk veld waarvan de naam token, password, IBAN, card of OTP bevat als ***, evenals elke parameter die een commando als geheim declareert.
LOGISTIVO_TOKEN — Persoonlijk access token. Zolang deze is gezet, wordt het configuratiebestand nooit gelezen — dit is de voorkeursroute in CI en op servers.
LOGISTIVO_BASE_URL — Root van de server. Standaard https://logistivo.com. Wijzig dit alleen als je naar je eigen omgeving wijst; de vlag --base-url doet hetzelfde voor één commando.
LOGISTIVO_HOME — Map voor het configuratiebestand en de cataloguscache. Standaard ~/.logistivo. Scheid ze als je met twee accounts op één machine werkt.
LOGISTIVO_PROFILE — Onder welk profiel er wordt gedraaid. `lg profile use` is de blijvende keuze; deze variabele geldt voor één run en is de kortste manier om in CI te wisselen tussen een live- en een sandboxprofiel. Een onbekende profielnaam wordt niet stilzwijgend genegeerd — dat geeft een fout.
NO_COLOR — Als deze is gezet, wordt er geen ANSI-kleur afgedrukt (de permanente vorm van de vlag `--no-color`). Zet hem aan voor een koppeling die naar een logbestand of CI-uitvoer schrijft; escapereeksen voor kleur breken de tools die die logs later lezen.
Ergonomie van de client
Deze functies maken het dagelijks gebruik van de `lg`-client makkelijker. Geen ervan verandert het HTTP-contract — sla deze sectie over als je rechtstreeks via HTTP integreert.
Meerdere omgevingen en sleutels — Houd staging en productie, of je klant- en vervoerderskoppelingen, in aparte profielen. De profiellijst toont nooit een token; elke rij toont de sha256-vingerafdruk van het token. De commandocatalogus wordt per profiel, host en token gecachet, zodat twee rollen nooit elkaars commandolijst kunnen zien.
Incrementele sync: lg sync — Draait de sync-lus uit het kookboek in één commando: een watermerk per entiteit, updated_since met een cursor, JSONL-uitvoer en een veiligheidsmarge van vijf minuten. Gebruik --full voor de eerste backfill. Het commando is alleen-lezen; er is geen vlag --write. lg sync --list leidt de synchroniseerbare entiteiten voor je rol af uit de catalogus.
Foutmeldingen en shell-completion — Bij 422 benoemt de client het geweigerde veld als de vlag die je hebt getypt, samen met de stabiele error_key en de eigen uitleg daarvan uit de catalogus. Bij 409 drukt hij de kant-en-klare opdrachtregel met --yes af; bij 429 wacht hij Retry-After af. Shell-completion dekt domeinen, werkwoorden, vlaggen en enum-waarden, en werkt offline.
Geheime parameters komen nooit op de opdrachtregel — Een paar commando's nemen een geheim aan — het koppelen van de boekhoudintegratie Paraşüt vraagt bijvoorbeeld de client credentials en het wachtwoord van dat systeem. lg accepteert zo'n waarde nooit als vlag, omdat die dan in je shellgeschiedenis en in de uitvoer van ps terechtkomt: het vraagt erom zonder echo, of leest het uit ---file=PATH of uit stdin (---file=-), en houdt het alleen in het geheugen. Een commando waarvan een verplichte parameter geheim is, draait alleen vanuit lg: aangeroepen vanuit de chat, via MCP of binnen lg batch wordt het geweigerd met SECRET_REQUIRES_CLI. Het auditlogboek legt de waarde altijd vast als ***.
Verbinden met een API-sleutel
Een ERP, CRM, script of AI-agent maakt verbinding met Logistivo via een integratiesleutel die is uitgegeven in het paneel of met lg keys create. De sleutel handelt namens een echt teamlid: de rol van die persoon bepaalt de commandolijst, het toegangsniveau van de sleutel bepaalt hoe zwaar het werk mag zijn, en wanneer die persoon het team verlaat, sterft de sleutel mee. Er is geen synthetisch "serviceaccount" en dat komt er ook niet — multi-tenant-isolatie is gebonden aan de gebruiker, en een koppeling zonder eigenaar is het soort dat jarenlang stilletjes blijft schrijven.
1. Geef een sleutel uit in het paneel — Settings › Integration keys › New key. Geef hem een naam ("ERP nachtelijke sync"), kies de scope en het toegangsniveau, en verkort eventueel de looptijd. De sleutel wordt één keer getoond, alleen op dat scherm; de server slaat hem niet op. Ben je hem kwijt, dan geeft Rotate een nieuwe uit — de oude wordt onmiddellijk ongeldig.
2. Verbinden vanuit de terminal — lg login --api-key valideert de sleutel, toont de identiteit en de scope, en downloadt de commandocatalogus. lg whoami vraagt de server als welke gebruiker, met welk bedrijf, welke rol en welke scope je draait. lg logout trekt de sleutel ook op de server in, net zoals het daar een sessie met een goedkeuringscode beëindigt (alleen de lg logout van een wachtwoordsessie kan dat niet).
3. Of gewoon HTTP — De sleutel is een access token dat in de header Authorization: Bearer wordt meegestuurd en werkt rechtstreeks tegen de drie commando-endpoints. Zet hem op een server of in CI in LOGISTIVO_TOKEN; zolang die variabele is gezet, wordt het configuratiebestand nooit gelezen.
4. Of beheer sleutels vanuit de terminal: lg keys — lg keys is de terminaltweeling van het paneelscherm: dezelfde endpoints, dezelfde controle (het recht voor teambeheer, en een sleutel op managerniveau wanneer je het met een sleutel aanroept). create, rotate en transfer geven één keer een nieuw token terug: met --save-profile=NAME gaat het rechtstreeks naar een lokaal profiel en wordt het nooit afgedrukt; anders drukt lg het één keer af. In de modus --json wordt het token alleen opgenomen als je --show-secret toevoegt, en een aanroep met --json zonder een van beide vlaggen wordt geweigerd voordat het verzoek wordt verstuurd, zodat het token niet ongemerkt in de uitvoer van een script kan belanden. rotate, transfer en revoke vragen om bevestiging (--yes); een sleutel wordt aangesproken met zijn exacte naam of zijn uuid, nooit met een gok. Het toegangsniveau gaat ongewijzigd over op een geroteerde of overgedragen sleutel.
De scope wordt gehandhaafd over het hele API-oppervlak, niet alleen in de commandocatalogus: een alleen-lezen-sleutel laat leesverzoeken (GET/HEAD/OPTIONS) door en elk ander schrijvend verzoek antwoordt met 403 forbidden. Er zijn twee bewuste uitzonderingen en beide worden bewaakt door een fijnere controle: het endpoint voor commando-uitvoering (de beslissing komt uit de eigen vlag read_only van het commando, omdat ook niet-schrijvende commando's met POST worden aangeroepen) en een sleutel die zichzelf intrekt (lg logout, ook toegestaan met een alleen-lezen-sleutel). Scope, domeinrechten en toegangsniveau zijn drie onafhankelijke assen en ze moeten alle drie slagen: een leessleutel kan zelfs op managerniveau niet schrijven, een schrijfsleutel op employee-niveau kan het team niet beheren, en een domeinrecht loads:write opent geen beheerwerk. Geef de sleutel uit namens het lid met de minste rechten dat aan je behoeften voldoet: de rol bepaalt welke records je überhaupt kunt zien.
read — De commandocatalogus en niet-schrijvende commando's (list, search, preview). Een schrijvend commando geeft 403 forbidden — vóór de bevestigingspoort; een alleen-lezen-sleutel ziet zelfs nooit een 409. De juiste keuze voor nachtelijke sync en rapportage.
write — Elk commando. Commando's die bevestiging vereisen, vragen er nog steeds om met 409; confirm: true (--yes in de CLI) werkt precies zoals voorheen. De scope versoepelt de bevestigingspoort nooit.
employee — De standaard voor elke nieuwe sleutel. Dagelijkse operaties: ladingen, aanvragen, biedingen, ritten, wagenpark en wagenparkdocumenten, documenten, contacten — elk commando dat geen beheerrecht nodig heeft, plus de wagenparkrechten. Een commando dat meer nodig heeft, antwoordt 422 met error_key INSUFFICIENT_KEY_LEVEL en required_key_level: manager; het bijbehorende REST-endpoint antwoordt 403 met dezelfde sleutel. Het juiste niveau voor een nachtelijke ERP-sync, een telematicakoppeling of een operationeel script.
manager — Alles wat de persoon namens wie de sleutel handelt mag doen, inclusief beheer: teamleden en rollen, bedrijfsinstellingen, integratiesleutels, bankrekeningen en de verificatie ervan, opgeslagen kaarten, bedrijfsrelaties, affiliate-uitbetalingen. Een managersleutel voegt nooit een recht toe dat de persoon niet heeft — zonder het recht voor teambeheer kan hij het team nog steeds niet beheren. Sleutels die al bestonden voordat toegangsniveaus werden ingevoerd, zijn managersleutels, dus ze gedragen zich precies zoals voorheen.
Eén sleutel per integratie — Delen CRM en ERP een sleutel, dan betekent de ene afsluiten ook de andere afsluiten. Geef elke koppeling een eigen sleutel; de lijst toont ze sowieso op naam.
Roteren — Geeft een nieuw token uit en trekt het oude onmiddellijk in; de resterende looptijd blijft behouden. Gebruik het bij een vermoeden van een lek en met regelmatige tussenpozen. De integratie krijgt 401 totdat ze met het nieuwe token is bijgewerkt.
Intrekken — De sleutel wordt permanent gesloten; dat kan niet ongedaan worden gemaakt, geef zo nodig een nieuwe sleutel uit. Wordt het lid namens wie de sleutel handelt uit het team verwijderd of gedeactiveerd, dan vervalt de sleutel vanzelf.
Looptijd en limiet — De standaardgeldigheid is 180 dagen; je kunt die bij het aanmaken verkorten, nooit verlengen. Een gebruiker kan maximaal 10 actieve sleutels hebben. Het tijdstip van laatste gebruik is zichtbaar in de lijst; bij een nooit gebruikte sleutel staat dat er expliciet bij.
Wie beheert — Uitgeven, roteren, overdragen en intrekken staat open voor managers met het recht voor teambeheer — dezelfde controle als voor het toevoegen of verwijderen van teamleden — en als het met een integratiesleutel gebeurt, moet die sleutel op managerniveau staan. Een manager kan namens een ander lid een sleutel uitgeven; voor een koppeling wordt een speciaal daarvoor bestemd lid met beperkte rechten aanbevolen.
De eerste tien minuten: van het paneel naar je eerste aanroep
De duurste minuten van een integratie zijn de eerste tien. De vier stappen hieronder zetten dat pad op volgorde; dezelfde volgorde bestaat in het paneel als wizard (Settings › Integration › Setup wizard), en de wizard roept precies de endpoints aan die hier worden beschreven. Een ontwikkelaar zonder toegang tot de wizard komt op dezelfde plek uit door deze sectie te lezen.
Geen van de vier stappen eindigt met "ik heb het verstuurd". Of de sleutel echt werkt, wordt beantwoord door het verzoekenlogboek; of de webhook echt aankomt, door het afleveringslogboek. Beide zijn open in het paneel en in lg. Een setup die nooit wordt gemeten, is een setup waarvan alleen wordt geloofd dat hij werkt.
1. Bepaal wat je gaat doen — stel eerst de scope in — Je kunt niet later beslissen wat een sleutel mag zien: je kiest de scope wanneer je hem uitgeeft. Er zijn twee assen. De grove scope (read / write) beantwoordt alleen "mag hij schrijven". De fijne scope (domeinrechten: loads:read, invoices:write) zegt welke domeinen hij mag aanraken, en zodra die is ingesteld, wordt de sleutel fail-closed — elk domein dat je niet hebt geselecteerd, en elk endpoint dat aan geen enkel domein is gekoppeld, geeft 403. De domeinlijst in het paneel is geen handgeschreven lijst; hij wordt afgeleid uit de live commandocatalogus van je rol en toont hoeveel commando's en REST-endpoints elk domein opent. De commandocatalogus en de endpoints "wie ben ik" (current) en "uitloggen" zijn altijd vrijgesteld van scope: een sleutel moet zichzelf altijd kunnen beschrijven en sluiten. De derde as is het toegangsniveau: employee (de standaard) voert dagelijkse operaties uit, manager doet ook werk rond team, instellingen, sleutels en geld. Kies employee, tenzij de koppeling beheerwerk doet.
2. Geef de sleutel uit — het token wordt één keer getoond — Settings › Integration › New key. Geef hem een naam ("ERP nachtelijke sync"), kies de gebruiker namens wie hij draait en het toegangsniveau, en verkort de looptijd als je wilt. Het ruwe token wordt alleen in dat antwoord teruggegeven; de server slaat het niet op en er is geen "opnieuw tonen" in het paneel. Ben je het kwijt, roteer dan om een nieuw token te krijgen; het oude sterft meteen. Zet het token nooit in versiebeheer, een CI-log of een chatvenster; zet het in de secret store van het doelsysteem.
3. Doe de eerste aanroep — en zie dat die ECHT is aangekomen — Twee verzoeken zijn genoeg. Het eerste bewijst je identiteit (het is vrijgesteld van scope en werkt met elke sleutel): is de scope wat je verwachtte, staat de status op active, nadert expires_at. Het tweede leest echte gegevens uit het domein dat je hebt gekozen. Slaagt het, dan zijn identiteit, scope, de e-mailcontrole en het netwerkpad allemaal in orde. Slaagt het niet, ga dan niet gokken: het eigen verzoekenlogboek van de sleutel laat rij voor rij zien welk endpoint werd geweigerd, met welke code en welke stabiele foutsleutel (INSUFFICIENT_SCOPE, IP_NOT_ALLOWED, KEY_ACTOR_BLOCKED …). In het paneel is dat logboek het venster "Recent requests"; in de terminal is het lg logs. De wizard bewaakt precies dit logboek en weigert de stap groen te maken totdat hij een echte geslaagde aanroep ziet.
4. Zet de webhook op — en verifieer de handtekening voordat je iets anders doet — Wachten op events is goedkoper dan elke minuut vragen. Registreer een https-adres, kies de events die je belangrijk vindt en bind het abonnement aan je sleutel: wordt de sleutel ingetrokken, dan stopt ook de aflevering. Het secret wordt maar één keer getoond, bij het aanmaken. Je ontvangende endpoint moet eerst de handtekening verifiëren: de ondertekende string is "{t}.{raw body}" en het algoritme is HMAC-SHA256; de tijdstempel zit BINNEN de handtekening, dus laat elk verzoek vallen dat ouder is dan 300 seconden, ook als de handtekening geldig is. Vergelijk in constante tijd en serialiseer de body nooit opnieuw — zodra je de JSON parseert en opnieuw afdrukt, klopt de handtekening niet meer. Vanuit het paneel vuurt "Send test" een echte ondertekende ping af en kun je de aflevering poging voor poging volgen.
Sandbox: schrijven oefenen zonder productie aan te raken
Preflight (dry_run) vertelt je wat een commando ZOU doen; maar of idempotency echt een replay geeft, of de webhook echt wordt afgeleverd, hoe de foutvertakkingen eruitzien en waar de credits vandaan komen, zie je alleen bij een ECHTE schrijfactie. Daar is de sandbox voor: een aparte tenant die je bedrijf spiegelt — dezelfde code, dezelfde commandocatalogus — en die nooit je live administratie aanraakt.
De sandbox is geen vlag in het verzoek, het is een TENANT. Een apart Logistivo-bedrijf dat voor het jouwe wordt geopend: een eigen gebruiker, een eigen pakket, een eigen creditadministratie, eigen webhookabonnementen. De omgeving wordt AFGELEID van het bedrijf van de sleutel en kan niet door de aanroeper worden meegegeven, dus zelfs als je het verkeerde profiel kiest, stopt het verzoek aan de serverkant met 403 ENVIRONMENT_MISMATCH. "Ik dacht dat ik naar de sandbox schreef en schreef naar productie" is structureel onmogelijk.
Het oppervlak is identiek — gemeten: de catalogus die een sandboxsleutel ophaalt, is dezelfde als die van je livesleutel (bij een verladerssleutel 646 commando's aan beide kanten). Een koppeling die in de sandbox werkt, werkt in productie; niets wat je leert, hoef je twee keer te leren.
De sandbox opent niet leeg: hij bevat gegenereerde (NIET gekopieerde) seeddata — contacten, ladingen in beide richtingen en aanvragen. De namen zijn openlijk verzonnen en de e-mailadressen vallen onder het domein @sandbox.invalid; er wordt nooit een rij van een echte tenant gelezen, gekloond of als sjabloon gebruikt.
Er is bewust GEEN resetknop, en er wordt nooit een record, bestand of document verwijderd. Wil je een schone start, dan opent een vernieuwing een nieuwe generatie en blijft de oude bestaan, buiten gebruik. Een paar honderd opgestapelde oefenrijen kosten niets vergeleken met een verwijderroutine die aan de verkeerde tenant is gekoppeld.
1. Open de sandbox — Eén sandbox per bedrijf. Het endpoint vereist het recht voor teambeheer (team.manage), dus een beheerder in je bedrijf doet dit. Bestaat hij al, dan antwoordt hetzelfde endpoint via GET met zijn toestand: bedrijfs-id, resterende credits, aantal actieve sleutels, abonnementen, generatiegeschiedenis en de maxima.
2. Geef een sandboxsleutel uit en bewaar die als tweede profiel — De sleutel wordt uitgegeven namens de eigen koppelingsgebruiker van de sandbox en komt terug met de stempel environment: sandbox; het ruwe token verschijnt alleen in dat ene antwoord. Vervang aan de kant van lg je livesleutel niet — bewaar ze ALLEBEI als aparte profielen; --sandbox en --live zijn kiezers voor één run.
3. Echt schrijven — Hier geen --dry-run; schrijven is juist het punt. Stuur dezelfde idempotency key twee keer en zie het tweede antwoord terugkomen als status: replayed — dat is het gemeten resultaat in de sandbox. Roep met opzet een bevestigingsplichtig commando aan zonder bevestiging en lees de body van de 409; probeer een commando buiten je scope en lees de weigering. Niets daarvan laat een spoor na in je live administratie: je live saldo blijft gedurende dezelfde run ongewijzigd.
4. Lees de checklist voordat je live gaat — Het go-live-endpoint antwoordt op basis van wat je ECHT in de sandbox hebt gedaan: heb je geschreven, heb je de foutvertakkingen gezien, is er een webhook afgeleverd, heb je de ontvanger van het oefenadres gehaald, heb je een vervaldatum op de sleutel gezet. Elk item komt terug als pass / todo / unknown. Hetzelfde antwoord bevat ook een SCOPEVOORSTEL dat is afgeleid van de commando's die je echt hebt aangeroepen — gebruik het om je livesleutel niet breder uit te geven dan je nodig hebt.
Credits en facturatie — De sandbox heeft een eigen creditadministratie en je live saldo beweegt niet. Dat is een structuur, geen controle: credits worden per bedrijf geteld en de sandbox is een apart bedrijf. Hij opent op het gratis niveau, heeft geen betaalmethode en valt buiten het maandelijkse incassovenster — langs geen enkele weg kan hij bij een factuur uitkomen.
Marketplace — Een aanvraag die je in de sandbox opent, verschijnt NIET op de schermen van echte vervoerders en bereikt NIET hun e-mail- of pushinbox; en jij ziet ook geen echte aanvragen. De scheiding is symmetrisch en wordt in twee aparte queries afgedwongen: voor wie een aanvraag ZICHTBAAR is en naar wie ze wordt VERSTUURD, zijn verschillende vragen.
Webhooks — Abonnementen dragen ook de omgevingsstempel. Een sandbox-event wordt nooit aan een live abonnement afgeleverd en een live event bereikt nooit een sandboxabonnement; voor een abonnement waarvan de stempel is afgedreven, wordt helemaal geen aflevering geopend. Omdat het maximum aantal abonnementen per bedrijf geldt, eten je oefenabonnementen niet van je live quotum.
Seeddata — De voorbeeldrecords in de sandbox zijn GEGENEREERD, nooit gekopieerd van echte tenants. Seeden is idempotent: een tweede aanroep legt geen tweede seed bovenop je eigen records.
Dezelfde catalogus — Je rol is ook in de sandbox je rol, en de commandolijst is identiek — gemeten, 646 commando's aan beide kanten. De sandbox is geen uitgeklede demo; hij is een tweeling van je bedrijf.
Huidige beperking: webhookabonnementen kunnen niet met een sandboxsleutel worden beheerd — De abonnementsendpoints vereisen het recht voor teambeheer (team.manage), en de koppelingsgebruiker van de sandbox heeft geen teamrol, dus `lg --sandbox webhooks …` antwoordt vandaag 403. Het hele commando-oppervlak werkt — de beperking geldt alleen voor het abonnementenregister. Wil je webhooks in de sandbox oefenen, vraag het dan aan support; dit is gemeten en vastgelegd als openstaand gat.
GET /api/common/integration-sandbox — Toestand: of hij bestaat, welk bedrijf, resterende credits, aantallen actieve sleutels en abonnementen, generatiegeschiedenis, de maxima, en een triggergids die laat zien welk commando welk event opwekt.
POST /api/common/integration-sandbox — Opent de sandbox (één per bedrijf, idempotent). Vereist het recht team.manage.
POST /api/common/integration-sandbox/keys — 201 + de sleutel en het ruwe token (alleen hier, alleen één keer). De stempel environment: sandbox wordt afgeleid van het bedrijf; de aanroeper kan hem niet meegeven.
GET /api/common/integration-sandbox/go-live — De go-live-checklist en een scopevoorstel — berekend uit je echte verkeer in de sandbox.
POST /api/common/integration-sandbox/renew — Opent een nieuwe GENERATIE van de sandbox en zet de vorige buiten gebruik.
Het commandomodel
Er is één grammatica en die kent geen uitzonderingen. Om te weten hoe je een commando aanroept, heb je alleen nodig wat de catalogus erover zegt.
lg loads list --status=in_transport --limit=20 --json
Vlagnamen zijn de parameternamen uit het schema, en lg accepteert beide schrijfwijzen: --load_code en --load-code bereiken hetzelfde veld (lg help toont de kebab-case-vorm). Aan een vlag zie je dus in welk JSON-veld hij terechtkomt, en de overstap van de CLI naar HTTP vraagt geen naamvertaling. Een booleaanse parameter zonder waarde is true (--only_open); het tegenovergestelde is --no-only_open. Schrijf een argument waarvan de waarde met een streepje begint als --flag=value, anders slikt een vergeten vlag stilzwijgend de volgende in als waarde. Bij een commando dat een bestand aanneemt, zet je @ voor een lokaal pad (--attachment_uuid=@./cmr.pdf) — zie Commando's die bestanden aannemen.
lg — De client.
loads — Het domein — de entiteit waaraan je werkt, in het meervoud.
list — Het werkwoord — wat je met die entiteit doet, uit een gesloten woordenschat die alleen door een bewuste beslissing groeit: eenvoudige werkwoorden (list, get, create, update, delete, search, preview, generate, extract …) en samengestelde werkwoorden die benoemen wat er wordt toegevoegd of gewijzigd (add-document, set-status, assign-driver). lg help toont de werkwoorden van een domein.
--status=in_transport — Een parameter — de naam is precies de parameternaam uit het JSON Schema en de waarde moet overeenkomen met het type in het schema. Een ongeldige waarde in een enum-veld bereikt de server nooit.
--limit=20 — Aantal rijen bij lijstcommando's. Het maximum staat in de parameterbeschrijving van elk commando — doorgaans 20 bij een gewone lijstaanroep en tot 100 in syncmodus (met cursor of updated_since).
--json — Ruwe JSON-uitvoer.
--json — Drukt ruwe JSON af. Dit is de enige juiste vorm voor scripts: de standaard uitgelijnde tabel is voor mensen, kiest haar kolommen op basis van de data en kan zonder aankondiging van indeling veranderen. Schrijf nooit een script dat de tabeluitvoer parseert.
--yes, -y — Passeert de bevestigingspoort (confirm: true via HTTP). Gebruik het alleen in een script dat weet wat het gaat doen; bij een onomkeerbaar commando is deze vlag een afkorting voor "er is geen weg terug".
--idempotency-key= — Maakt het veilig om een schrijvend commando opnieuw te proberen. Een tweede aanroep met dezelfde sleutel voert het commando niet opnieuw uit; hij geeft het eerste resultaat terug. Bouw je een retrylus, genereer de sleutel dan ZELF en stuur bij elke poging dezelfde.
--dry-run — Voert een preflight uit in plaats van het commando: validatie, de controles en de creditberekening draaien, er wordt niets geschreven (zie de sectie over preflight). Geldig bij elk commando en bij lg batch.
--refresh — Forceert een verversing van de catalogus. lg cachet de catalogus een uur; als je weet dat er net een commando op de server is toegevoegd, gebruik dan dit in plaats van te wachten.
--help, -h — Toont de catalogusbeschrijving van het commando, elke parameter, het type, de enum-waarden en of de parameter verplicht is. Er zit geen helpbestand in de client.
--profile=, --sandbox, --live — Onder welk profiel deze ene aanroep draait. --sandbox en --live kiezen het profiel met een sandbox- of een livesleutel; de omgeving wordt op de server afgeleid van de sleutel, dus bij een mismatch stopt het met 403 ENVIRONMENT_MISMATCH in plaats van naar de verkeerde plek te schrijven.
--base-url, --timeout, --verbose, --no-color, --version — Respectievelijk: één commando naar een andere server laten wijzen, een timeout in seconden, details van request en response, ANSI-kleur uitschakelen, en de clientversie.
Echte voorbeelden
Elk commando hieronder bestaat vandaag in de catalogus; geen enkele naam of parameter hier is verzonnen. De uitvoer is ingekort. De uitvoer toont het niveau `data.result`; via HTTP komt hetzelfde object binnen in de envelop `{success, data:{…}}` (zie de HTTP-commando-API).
Ladingen die nu onderweg zijn — lg loads list --status=in_transport --limit=20
Eén lading volledig, ruwe JSON — lg loads get --load_code=FSK2158 --json
Openstaande meldingen over documentconsistentie — lg loads list-problems --only_open=true --limit=10
Het land bepalen — lg countries search --query=Germany --json
Filteren met de gevonden id — lg loads list --receiving_country_id=57 --date_from=2026-09-01 --limit=20
Een HS-code vinden op basis van een productnaam — lg tariffs search --query="aluminium profile"
Een lading een stap verder zetten (alleen vervoerdersrol) — lg loads set-status --load_code=FSK2158 --status=transit --date=2026-08-21 --yes
Concept — lg export-documents create --doc_type=proforma-invoice --currency_code=EUR --json
Genereren (bevestigingsplichtig) — lg export-documents generate --document_id=8412 --yes
Zonder de client: de HTTP-commando-API
lg is een gemak, niet de toegangsdeur. Catalogus en uitvoering lopen allebei via drie HTTP-endpoints (bestanden hebben een vierde, het upload-endpoint — zie Commando's die bestanden aannemen); een ERP- of CRM-integratie maakt hier rechtstreeks verbinding. De identiteit is een persoonlijk access token dat wordt meegestuurd in Authorization: Bearer. ELK antwoord komt terug in dezelfde envelop: `{ "success": bool, "data": { … }, "code": "…", "message": { … } }`. Het hele contract zit in `data` — `contract_version`, `command`, `status` en, als uitvoer van het commando, `result`; bij een fout `error_code`, `error_key` en `error`. De antwoordvoorbeelden op deze pagina tonen het object `data` in plaats van de envelop, om ruimte te besparen; vergeet niet om in je eigen code `data` uit te pakken. Ook `lg --json` drukt de HELE envelop af, en daarom beginnen jq-paden met `.data.result…`. De enige uitzondering is `/api/public/status`: dat endpoint is envelopvrij, zodat watchdogs kunnen alarmeren zonder het te parseren.
Om bevestiging vragen met 200 + ok:false is verboden en zal nooit gebeuren. De reden is eenvoudig: clients behandelen 200 als succes, dus een bevestigingsverzoek dat als 200 terugkomt, zou de flow stilletjes doden en niemand zou het merken. Bevestiging is altijd 409.
GET /api/common/commands — De hele catalogus die je rol kan zien: contract_version; per commando name, domain, verb, description, JSON Schema, read_only, confirmation_needed, irreversible, credit_cost, since, deprecated_at, replaced_by, aliases en de toegangsvelden key_level, permission, file_params, secret_parameters en cli_only; op het hoogste niveau het woordenboek error_keys, rate_limits, idempotency_ttl_hours, je catalogusrollen, het contract voor attachments (upload) en het toegangsniveau van de sleutel waarmee je aanroept. Stuurt een ETag mee; If-None-Match antwoordt 304. ?domain= matcht ook een oud domein (alias). Bouw je client hieruit op; codeer geen commandolijst hard.
GET /api/common/commands/{name} — Eén commando volledig. name is de bevroren commandonaam uit de catalogus (list_loads), niet de CLI-identiteit. Een verouderd commando antwoordt met een header X-Deprecated.
POST /api/common/commands/{name} — Uitvoering. Body: { args, confirm?, idempotency_key? }. De HTTP-status van het antwoord is het resultaat zelf — alles behalve 200 is informatie, geen ruis. Fouten dragen error_code (transport) en, bij zakelijke afwijzingen, error_key.
Commando's die bestanden aannemen
38 commando's in de tabel nemen een document of foto aan: een CMR aan een lading koppelen, HS-codes uit een factuur lezen, een voertuig aanmaken op basis van het kentekenbewijs, een pallet schatten op basis van foto's, een bedrijfsdocument uploaden, een factuur vergelijken met een paklijst. In de browser sleep je het bestand naar een formulier; overal elders kost het twee stappen — het bestand uploaden en daarna de id ervan aan het commando doorgeven.
Een parameter neemt een bestand aan wanneer de naam eindigt op attachment_uuid of attachment_uuids — photos[].attachment_uuid binnen een lijst, front_attachment_uuid bij een cheque. Dat hoef je niet te onthouden: elke catalogusrij bevat file_params met de exacte paden, het schema markeert die velden (format: uuid, x-logistivo-file: true), en het catalogusantwoord bevat een blok attachments met het uploadadres, de geaccepteerde types, de groottelimieten en de geldigheidsduur. lg help toont ze ook.
Uploaden is een schrijfactie, dus een sleutel met leesscope kan niet uploaden; elke sleutel met schrijfscope kan het wel, op beide toegangsniveaus. Uploads horen bij de gebruiker, niet bij de sleutel: twee sleutels van dezelfde gebruiker zien dezelfde uploads, en niemand kan die van iemand anders gebruiken. Een id die onbekend, verlopen of niet van jou is, wordt simpelweg niet gevonden, en de reden wordt niet bekendgemaakt.
Bijlagen in de dashboardchat en commando-uploads zijn gescheiden ruimtes: een bestand dat in de assistentchat is bijgevoegd, kan niet via de id aan een commando worden doorgegeven, en een commando-upload verschijnt nooit in een chatgesprek.
Een upload is geen commando en heeft op zichzelf geen zakelijk effect: er gebeurt niets met je gegevens totdat een commando de id gebruikt. Daarom vraagt uploaden ook nooit om bevestiging — het commando dat het bestand gebruikt, draagt de poort.
1. lg: zet @ voor een lokaal pad — lg uploadt het bestand eerst en voert daarna het commando uit met de teruggegeven id; een waarde zonder @ is de id van een bestand dat je eerder hebt geüpload. Lijsten nemen door komma's gescheiden paden of een herhaalde vlag aan, geneste velden nemen JSON aan, en --file is een snelkoppeling wanneer het commando precies één bestandsveld op het hoogste niveau heeft. lg controleert elk bestand lokaal (bestaat het, grootte, type) voordat er iets wordt verstuurd, en lg batch uploadt elk afzonderlijk bestand één keer voordat de batch draait.
2. HTTP: uploaden, daarna attachment_uuid doorgeven — Stuur het bestand als multipart/form-data in een veld met de naam file. Een nieuwe upload antwoordt 201; hetzelfde bestand dat door dezelfde gebruiker opnieuw wordt geüpload, antwoordt 200 met status replayed en dezelfde id, en er wordt niets geschreven. Zoals overal op deze pagina toont het voorbeeld het object data binnen de envelop.
3. MCP: de tool upload_attachment — Een MCP-client kan geen multipart versturen, dus het kanaal biedt één extra tool die niet in de catalogus staat: upload_attachment neemt een bestandsnaam en de inhoud als base64 aan en geeft dezelfde attachment_uuid terug. Hij roept dezelfde service aan als de HTTP-upload, onder dezelfde regels.
Het type komt uit de inhoud — De bestandsnaam en het opgegeven type worden genegeerd; de opgeslagen extensie is de gedetecteerde. Geaccepteerd voor upload: jpg, jpeg, png, webp, heic, heif, pdf, xlsx, xls, csv, txt, doc, docx, xml, zip. Elk commando past daarna zijn eigen, smallere lijst toe voordat er iets draait en antwoordt met UNSUPPORTED_FILE_TYPE en de geaccepteerde types, of met FILE_TOO_LARGE.
Grootte — Afbeeldingen tot 10 MB, andere bestanden tot 15 MB.
Geldigheidsduur — Een upload kan 24 uur worden gebruikt. Daarna wordt hij niet meer opgelost (ATTACHMENT_NOT_FOUND) — hij wordt niet verwijderd. Upload opnieuw als een commando om die reden mislukt.
Zelfde bestand, zelfde id — Hetzelfde bestand opnieuw uploaden (zelfde naam, grootte en inhoud) geeft de bestaande id terug in plaats van een nieuwe te schrijven, zolang die nog minstens een uur geldig is, en het telt niet mee voor je dagelijkse maximum.
Dagelijkse maxima — 300 uploads per gebruiker per dag (TOO_MANY_FILES) en 2 GB per bedrijf per dag (DAILY_LIMIT_REACHED); beide antwoorden 429 met retry_after.
POST /api/common/commands:upload — Multipart-upload in het veld file. 201 voor een nieuwe upload, 200 met status replayed voor hetzelfde bestand. Geeft data.attachment terug: attachment_uuid, filename, mime_type, size_bytes, sha256, extraction_status, expires_at en reused.
De bevestigingspoort en onomkeerbare commando's
Elk commando in de catalogus draagt twee vlaggen: confirmation_needed (is er expliciete goedkeuring nodig voordat het draait) en irreversible (kan het effect ongedaan worden gemaakt). Het zijn afzonderlijke vragen, en beide worden op de server gehandhaafd in plaats van overgelaten aan de goede manieren van de client.
De poort gaat over verantwoordelijkheid, niet over bedrijfsregels. Een bod uitbrengen is de eerste stap naar een vrachtcontract; een factuur uitgeven maakt een boeking in de boekhouding aan; een voorraadmutatie wijzigt een grootboek. Geen van deze mag ooit iets zijn dat je per ongeluk twee keer kunt uitvoeren.
De poort wordt gelezen van het EFFECTIEVE commando. Wanneer het ene commando het andere omhult — zoals de generieke uitvoerder in de chat doet — komt de poort uit de vlaggen van het commando dat daadwerkelijk zal draaien, niet van de wrapper. Met een vaste vlag zou een van twee fouten onvermijdelijk zijn: óf het factuurcommando zou onbevestigd draaien, óf elke opzoeking van een land zou een bevestigingskaart oproepen.
read_only en niet bevestigingsplichtig zijn niet hetzelfde. Er zijn drie verschillende toestanden: invoices preview is niet bevestigingsplichtig en schrijft niets; loads create is bevestigingsplichtig en schrijft; invoices create is niet bevestigingsplichtig maar schrijft wel — er ontstaat een concept. Eén test beslist: is er, wanneer het commando terugkeert, een rij in de database veranderd?
Sommige acties zitten niet achter deze poort, omdat het helemaal geen commando's zijn: een pakket kopen, een kaart toevoegen met 3D Secure, juridische teksten goedkeuren en een account sluiten gebeuren in de eigen browser van de persoon. Daarvoor geeft lg handoff-links generate een logistivo.com-link terug — gratis, zonder iets te schrijven, zonder geheim — en de persoon rondt de stap daar af. Geen enkele vlag, hoe die ook staat, maakt van een betaling of een toestemming een API-aanroep.
Technisch kan een integratie de poort bij elke aanroep automatisch passeren, maar dat is niet aan te raden. Het juiste patroon is de poort alleen te automatiseren voor commando's waarvan je weet dat ze omkeerbaar zijn, en onomkeerbare commando's naar de wachtrij van een mens te leiden.
1. Aanroepen — Roep het bevestigingsplichtige commando aan zonder confirm. Er verandert niets.
2. Lees de samenvatting — Je krijgt een 409; confirmation.summary in de body is een zin die voor een mens is geschreven ("About to issue an invoice: X Ltd, 1,200.00 TRY"), geen dump van ruwe argumenten. Monetaire commando's bevatten ook een gestructureerde preview: regelitems, totalen, waarschuwingen.
3. Bevestigen — Herhaal dezelfde aanroep met confirm: true (--yes in de CLI). Onomkeerbare commando's zijn zo gemarkeerd dat ze hoogstens één keer draaien.
Preflight: zien wat een schrijfcommando zou doen, zonder het uit te voeren
De duurste stap bij het aansluiten van een ERP-koppeling is uitvinden of je body klopt door het commando ECHT uit te voeren: een conceptfactuur in het live grootboek, een verbrande credit, handmatig opruimen. dry_run maakt daar een einde aan — je voegt één veld toe aan het verzoek, het commando draait niet, en je leest wat er zou gebeuren.
Het register bevat vandaag 721 commando's; 327 daarvan lezen alleen en schrijven niets. Van de overige 394 schrijfcommando's zijn er 346 bevestigingsplichtig: zonder confirm aangeroepen antwoorden ze al met 409 en beschrijven ze wat ze zouden doen. Het gat zat in de andere 48 — factuurconcepten, concepten van exportdocumenten, regelitems: precies de keten die een koppeling als eerste aansluit. Voor die commando's was aanroepen hetzelfde als uitvoeren.
Zelfs bij bevestigingsplichtige commando's was er een tweede gat: schemavalidatie draait NA de poort. Een aanroep met een ontbrekend argument kreeg dus eerst de bevestigingskaart, bevestigde die, en hoorde pas daarna "dit veld ontbreekt". Een preflight beantwoordt beide in één round trip.
En de meest voorkomende — en het laatst ontdekte — koppelingsbug is deze: je stuurt een veld dat niet in het schema staat (customer_id waar recipient_contact_id wordt verwacht), de server laat het stilzwijgend vallen, het commando geeft 200 terug en het record belandt op de verkeerde plek. Het preflight-antwoord noemt die velden bij naam onder arguments.ignored; een foutmelding zal dat nooit doen.
Een preflight schrijft niets, en dat is structureel nog voordat het een meting is: het preflightpad komt nooit in de handler van het commando, dus het geldt voor elk commando, ook voor de later toegevoegde. Het werd bij de lancering ook gemeten: elk SQL-statement dat werd uitgevoerd tijdens het preflighten van elk schrijfcommando dat toen in de catalogus stond (twee sets argumenten, twee rollen, 178 preflights), werd vastgelegd. Geen enkele INSERT/UPDATE/DELETE, geen enkele job in de wachtrij, geen enkele e-mail; het aantal rijen in 31 tabellen en het creditsaldo bleven ongewijzigd.
De exitcode is dezelfde die de echte aanroep zou geven — zou draaien 0, bevestigingspoort 4, idempotency-conflict 2, al het andere 1 — dus "lg … --dry-run || exit" is een zinvolle poort in een CI-stap.
1. Aanroepen met dry_run — Voeg "dry_run": true toe aan de request body. Validatie, de rol- en scopecontrole, doelresolutie en de creditberekening draaien allemaal; het commando niet.
2. Lees would_execute — Dat is de enige vlag waarop je vertakt. Als die false is, noemt would_stop.at waar een echte aanroep zou stoppen: idempotency, target_precheck, confirmation_gate of arguments.
3. Je body repareren — arguments.ignored noemt de velden die stilzwijgend zouden wegvallen, missing_required de verplichte velden die je bent vergeten, en would_charge hoeveel credits er zouden worden afgeschreven en of het saldo die dekt.
4. dry_run weglaten — Herhaal totdat would_execute true is, verwijder dan de vlag en doe de echte aanroep. De idempotency key die je tijdens de preflight stuurde, is niet opgebruikt, dus de echte aanroep draait normaal.
HTTP is altijd 200 — "Het commando zou mislukken" komt nooit binnen als 4xx — de preflight zelf is geslaagd en de voorspelling staat in de body. De uitzondering is een weigering op transportniveau, en daar gedraagt het zich precies als een echte aanroep: 404 onbekend commando, 403 rol/scope, 429 rate limit.
Een sleutel met leesscope kan geen dry run van een schrijfcommando doen — Hij krijgt 403. Een preflight beantwoordt "wat gebeurt er als ik dit MET DEZE SLEUTEL aanroep, nu"; een leessleutel groen licht geven en daarna een 403 bij de echte aanroep zou precies de verrassing zijn die de preflight moet voorkomen.
De idempotency key wordt niet opgebruikt — Een sleutel die tijdens een preflight wordt gestuurd, opent geen regel in het logboek, en een verlopen lock wordt niet vrijgegeven. Stuur dus de sleutel die je echt wilt gebruiken: de preflight vertelt je of hij nog vrij is, een eerdere uitvoering zou herhalen (replay) of botst met een ander commando.
Hij combineert met confirm — Stuur dry_run en confirm samen en de vraag wordt "als ik bevestig, wat gebeurt er dan?". Nog steeds draait er niets.
Batch-preflight geldt per batch — commands:batch accepteert ook dry_run, maar de vlag hoort bij de batch, niet bij een item (op een item meesturen geeft 422). Je krijgt een rapport per item plus de totale creditkosten van de batch; een ontoereikend saldo wordt gemeld, niet geweigerd.
Hij is niet gratis — Elke preflight voert echte queries uit (preview, saldo) en telt mee voor de rate limit. Doe niet bij elke deploy een preflight van de hele catalogus; doe een preflight van de commando's die je hebt gewijzigd.
Idempotency: waarom opnieuw proberen geen duplicaten oplevert
Een ERP leest je foutmelding niet, ziet je scherm niet en stuurt na een timeout hetzelfde verzoek opnieuw. Deze sectie bestaat precies voor dat gedrag.
Een aanroep met een idempotency_key draait hoogstens één keer. De tweede aanroep voert het commando niet opnieuw uit; hij geeft het vastgelegde resultaat terug met status replayed. Valt het netwerk weg, verloopt een verzoek of pakt een wachtrij dezelfde job twee keer op, dan krijg je het eerste resultaat in plaats van een dubbele factuur.
Gebruik een sleutel bij elk schrijvend commando. Het veld read_only in de catalogus geeft je dat onderscheid gratis: elk commando met read_only: false verdient een idempotency key.
Je retrystrategie moet exponential backoff gebruiken en bij elke poging DEZELFDE sleutel meesturen. Per poging een nieuwe sleutel genereren is hetzelfde als helemaal geen idempotency gebruiken. Stuur dezelfde sleutel niet parallel: at-most-once is gegarandeerd voor opeenvolgende retries, niet voor twee verzoeken die met elkaar racen.
Valkuil 1 — ook een mislukking wordt vastgelegd — Als de eerste uitvoering door een bedrijfsregel werd afgewezen (failed), geeft een tweede aanroep met dezelfde sleutel dezelfde fout en dezelfde error_key terug en probeert hij het niet opnieuw. Om het argument te corrigeren en het opnieuw te proberen heb je een NIEUWE sleutel nodig. Een sleutel staat voor een poging, niet voor een intentie.
Valkuil 2 — een groot resultaat wordt zonder body herhaald — Het logboek slaat een resultaat alleen op als het kleiner is dan 64 KB. Een groter resultaat wordt herhaald met status replayed, maar met een lege body. Je integratie moet vertrouwen op het signaal "replayed" in plaats van op de body, en de gegevens ophalen met het bijbehorende get-commando.
Valkuil 3 — een sleutel hoort bij één commando — Dezelfde sleutel met een ander commando sturen geeft 409 idempotency_conflict terug met de conflicting_command; er draait niets en er wordt niets herhaald. Een client die één sleutel deelt over twee werkwoorden is kapot en leert dat van een foutmelding, niet van een stille replay.
Valkuil 4 — de lock duurt 24 uur, niet eeuwig — Na 24 uur is dezelfde sleutel een nieuwe uitvoering. Netwerk-retries komen binnen enkele minuten binnen; de jaarlijks terugkerende documentnummers van een ERP mogen niet voor altijd "replayed" blijven. De catalogus publiceert het venster als idempotency_ttl_hours.
Valkuil 5 — een serverfout vergrendelt de sleutel niet — Een 5xx server_error is geen zakelijke afwijzing: de sleutel wordt niet gebonden, dus een nieuwe poging met dezelfde sleutel voert het commando echt uit. Alleen failed vergrendelt (valkuil 1).
Scope en formaat — je bedrijf, elke string, bij voorkeur een UUID — Uniciteit wordt afgedwongen op (je bedrijf, sleutel): de INV-1001 van een andere tenant botst nooit met de jouwe en kan nooit jouw resultaat herhalen. Gebruik een gewone UUID of een samenstelling die per constructie uniek is, zoals {ERP-document-no}:{verb}.
Incrementele sync en paginering
Een ERP/CRM-koppeling moet ophalen wat er veranderd is, niet elk uur alles. Elk lijstcommando — loads list, demands list-own, contacts list, invoices list, teammates list, load-groups list, reservations list, drivers list, tenders list, products search, warehouses search — accepteert twee gedeelde parameters en geeft één gedeeld veld terug.
Waarom er geen offset is: op een live tabel verschuift een offset. Een rij die tussen twee pagina's wordt ingevoegd, laat je een record overslaan of dubbel tellen, zonder dat je het merkt. De cursor gaat alleen vooruit, dus een record dat halverwege wordt ingevoegd of bijgewerkt, belandt aan het eind van de lijst: er gaat niets verloren en niets wordt gedupliceerd.
Een volledige eerste import is hetzelfde mechanisme: begin met updated_since=1970-01-01T00:00:00Z en volg next_cursor totdat die null is. Er is geen apart “export”-endpoint, omdat dat niet nodig is.
Hetzelfde met lg: lg loads list --updated_since=2026-09-01T00:00:00Z --limit=100 --json, daarna lg loads list --cursor= --json.
Zet voor de volgende sync updated_since op de grootste updated_at die je hebt gezien. Tijdstempels hebben een precisie van één seconde, dus een record op de grens kan twee keer binnenkomen — onschuldig zolang je aan jouw kant upsert op external_ref of code. Zonder updated_since of cursor draait een commando in chatmodus: menselijke ordening, hoogstens 20 rijen, next_cursor null en truncated die zegt “er is meer”. Gebruik die modus niet voor sync.
Machineleesbare foutsleutels voor deze sectie: INVALID_CURSOR, INVALID_UPDATED_SINCE, DUPLICATE_EXTERNAL_REF, EXTERNAL_REF_TOO_LONG, EXTERNAL_REF_INVALID. Ze antwoorden allemaal met HTTP 422 met error_code: "failed" en result.error_key in de body. Vertak op de sleutel, nooit op de tekst.
updated_since — ISO-8601-tijdstempel (UTC aanbevolen, bijv. 2026-09-01T00:00:00Z). Rijen die op of na dit moment zijn bijgewerkt. Het zet het commando in syncmodus: vaste volgorde (updated_at, id) oplopend, limit begrensd op 100.
cursor — De next_cursor uit het vorige antwoord, letterlijk. Hij is ondoorzichtig en ondertekend: bouw of bewerk er nooit een, en hergebruik nooit de cursor van een ander bedrijf of een ander commando; al deze gevallen worden geweigerd met INVALID_CURSOR.
limit — Paginagrootte. 1-100 in syncmodus (standaard 10).
next_cursor (respons) — Cursor voor de volgende pagina. null betekent dat de lijst compleet is; het is het enige juiste antwoord op “is er meer”.
total (respons) — Rijen die aan de filters voldoen, onafhankelijk van de pagina — voor voortgangsrapportage.
Je eigen sleutel: external_ref
Maak onze auto-increment-id's (invoice_id, contact_id) niet de bedrijfssleutel in je ERP; ze zijn ondoorzichtig en privé voor je bedrijf. Ladingen, aanvragen, contacten, facturen, producten en magazijnen dragen in plaats daarvan jouw sleutel.
Zet hem bij het schrijven — loads create, demands create, contacts create en contacts update, invoices create accepteren een optionele external_ref (max. 120 tekens) en geven die ongewijzigd terug.
Gebruik hem bij het lezen — loads get --external_ref=ORD-2026-0917, invoices get --external_ref=..., contacts get --external_ref=..., demands get --external_ref=... werken allemaal; bij lijst- en zoekcommando's is --external_ref= een filter op exacte overeenkomst.
Uniek per bedrijf — Een tweede record met dezelfde sleutel wordt geweigerd met 422 en result.error_key = DUPLICATE_EXTERNAL_REF; de sleutel van een ander bedrijf geeft jou “niet gevonden”. Matching is niet hoofdlettergevoelig (ord-1 = ORD-1). Een gearchiveerd record behoudt zijn sleutel; herstel het voordat je de sleutel hergebruikt.
Stuur ook een idempotency_key mee — Een nieuwe poging na een netwerktimeout geeft het eerste resultaat terug in plaats van een duplicaat aan te maken. De twee zijn niet uitwisselbaar: external_ref is jouw bedrijfssleutel, idempotency_key identificeert één poging.
Uitgaande webhooks: wij sturen je een POST wanneer er iets gebeurt
Alles tot hier was pull: jij vraagt, wij antwoorden. Een ERP-koppeling moest elke minuut vragen om te weten te komen dat een lading van status was veranderd, een factuur was uitgegeven of een bod was binnengekomen. Nu niet meer: registreer een https-adres, kies de events die je belangrijk vindt, en er komt een ondertekende POST binnen wanneer ze gebeuren.
Push werd NAAST pull toegevoegd, niet in plaats ervan. Incrementele sync (updated_since + cursor) is onaangetast en nog steeds het juiste gereedschap: de eerste volledige import, het aanvullen van historie en het beantwoorden van "heb ik iets gemist" gebeuren daar allemaal. Webhooks brengen de latency terug van minuten naar seconden. Een gezonde koppeling gebruikt beide — de webhook als trigger, de sync als vangnet.
De payload is een SIGNAAL, geen kopie van het record. Hij bevat de identifiers (id, je eigen external_ref, status, tijd); de details haal je op met je eigen sleutel via GET, en die aanroep gaat al door je eigen autorisatiecontroles. Het blootstellingsoppervlak blijft dus op het niveau van identifiers. Twee velden ontbreken bewust: de identiteit van het bedrijf dat een bod heeft uitgebracht (blinde biedingen verschijnen in het paneel onder een alias; de identiteit in een webhook opnemen zou die privacy via een tweede kanaal doorbreken) en de contactgegevens van reserveringen (er is geen reden om persoonsgegevens via een extra kanaal te verplaatsen).
Eventnamen zijn BEVROREN. Verandert de betekenis van een naam, dan wordt er een nieuwe naam geopend en leeft de oude door tijdens een uitfaseringsperiode. Een nieuw veld aan de payload toevoegen verhoogt de contractversie NIET — een consument moet velden negeren die hij niet kent.
GET /api/common/integration-webhooks — Het logboek plus de eventcatalogus, de limieten en de headernamen. Elke rij bevat de reden van stillegging en een afleveringsoverzicht over 7 dagen.
POST /api/common/integration-webhooks — 201 + { webhook, secret, shown_once: true }. Het secret verschijnt alleen hier.
PATCH /api/common/integration-webhooks/{uuid} — Naam / adres / events / vlag active. Raakt het secret NIET.
DELETE /api/common/integration-webhooks/{uuid} — Verwijdert het: de rij wordt soft-deleted (de historie blijft opvraagbaar) en openstaande afleveringen worden geannuleerd.
POST /api/common/integration-webhooks/{uuid}/rotate-secret — 201 + een nieuw secret. De oude waarde werkt vanaf dat moment niet meer.
POST /api/common/integration-webhooks/{uuid}/test — Een ping-event — echte handtekening, echt pad, echt retryschema.
GET /api/common/integration-webhooks/{uuid}/deliveries — De meest recente afleveringen: status, pogingnummer, HTTP-code, duur, fouttag.
POST /api/common/integration-webhooks/deliveries/{uuid}/replay — Verstuurt één aflevering opnieuw: event_id BLIJFT BEHOUDEN, de aflever-id is nieuw, de payload wordt letterlijk gekopieerd.
Eventcatalogus
Elk van de 13 events hieronder wordt gedekt door een eventklasse die ECHT wordt verzonden. Er staan geen namen van het type "zou leuk zijn" in de catalogus: een event dat wordt aangekondigd maar nooit afgaat, is een event waar de integrator eeuwig op wacht, en die fout is stil. Ook deze tabel is niet met de hand geschreven — hij wordt bij elke paginaweergave uit de live catalogus opgebouwd.
invoice.payment_recorded ontbreekt BEWUST: die eventklasse bestaat in de code, maar wordt nergens vandaan verzonden. Het betalingsevent wordt toegevoegd op de dag dat de klasse echt wordt afgevuurd — niet eerder. Een event te vroeg aankondigen is erger dan het nooit toevoegen.
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)
De handtekening verifiëren
Elk verzoek bevat een header X-Logistivo-Signature: t=,v1=. De ondertekende string is "." en het algoritme is HMAC-SHA256. Het voorvoegsel v1 houdt het schema versioneerbaar: komt er ooit een tweede schema, dan bevat de header t=…,v1=…,v2=… en kies je degene die je kent.
We publiceren twee referentie-ontvangers zonder afhankelijkheden, één voor Node en één voor gewoon PHP. Beide passen de vier regels hierboven toe en testen zichzelf met --selftest: geldige handtekening, gemanipuleerde body, verkeerd secret, tijdstempel buiten het venster, misvormde header, de valkuil van het opnieuw serialiseren en beide soorten herhaling (dezelfde aflevering / hetzelfde feit). De verifier is de exacte tegenhanger van de code die we zelf gebruiken — we consumeren het contract dat we publiceren.
Verifieer de RUWE body — De handtekening wordt over bytes berekend. De body decoderen en opnieuw serialiseren (JSON.stringify(req.body), json_encode($request->all())) maakt van dezelfde DATA andere BYTES en dan klopt de handtekening niet meer. In Node zit de valkuil in de getalnotatie (1.50 op de lijn wordt 1.5; grote gehele getallen verliezen precisie), in PHP in het escapen van tekens (/ wordt \/, İ wordt \u0130). Gebruik express.raw in Express en $request->getContent() in Laravel. Dit is verreweg de meest gemaakte fout bij het schrijven van een ontvanger.
Controleer de tijdstempel — t zit BINNEN de handtekening. Alleen de handtekening verifiëren laat iedereen die een geldig verzoek heeft onderschept, het uren later opnieuw afspelen, en de ontvanger zou het als geverifieerd event tellen. Laat elk verzoek vallen waarbij |now − t| > tolerance, ook als de handtekening klopt. Het aanbevolen venster is 300 seconden.
Vergelijk in constante tijd — hash_equals / timingSafeEqual. Vergelijken met == laat een aanvaller de handtekening byte voor byte raden.
Ontdubbel op event_id, niet op id — event_id identificeert het FEIT: het is hetzelfde voor twee abonnees die hetzelfde event ontvangen, en het BLIJFT BEHOUDEN bij een replay. id (= X-Logistivo-Delivery) identificeert de AFLEVERING en verandert bij een replay. Beantwoord "heb ik dit al verwerkt" met event_id; als je het met id beantwoordt, voert een replay hetzelfde werk twee keer uit.
Aflevering, retries en stillegging
Je ontvanger zal niet altijd bereikbaar zijn. Het spoor gaat daarvan uit: een tijdelijke fout komt in het retryschema, een permanente fout legt het abonnement stil — en de REDEN van stillegging wordt altijd vastgelegd.
De reden van stillegging is machineleesbaar en stabiel (delivery_failures, endpoint_gone, unsafe_target, key_revoked, by_user) en verschijnt zowel in het paneel als in `lg webhooks list`. Stilleggen zonder reden zou de vraag "waarom komt er niets binnen" onbeantwoordbaar maken. Opnieuw inschakelen zet de teller en de stempel terug.
Jij schrijft het adres; ONZE server doet het verzoek. Zonder controle zou een tenant die een metadata-adres van een cloud invoert, ons verzoeken kunnen laten doen vanuit ons eigen netwerk. Daarom wordt het adres gecontroleerd bij registratie en bij ELKE aflevering:
Timeouts — 8 s in totaal, 4 s om te verbinden — een trage ontvanger mag geen worker bezet houden. Zet het werk in een wachtrij en geef meteen 2xx terug.
Retryschema — 60 · 300 · 1800 · 7200 · 21600 seconden → 6 pogingen, een venster van ongeveer 8,6 uur.
De enige permanente fout: 410 Gone — Het betekent "verwijder me": geen retry, het abonnement wordt meteen stilgelegd. Geef NOOIT 410 terug bij een mislukte handtekeningcontrole.
Elke andere fout — ALLE worden opnieuw geprobeerd, 4xx inbegrepen. Een zakelijk event verliezen kost meer dan een paar extra verzoeken: een ontvanger die 403 teruggeeft terwijl er een WAF-regel wordt bijgewerkt, zou op een spoor dat 4xx als permanent behandelt stilletjes een event "factuur uitgegeven" verliezen.
Retry-After — Gerespecteerd bij 429 en 503 (maximaal 6 uur).
Redirects — WORDEN NIET gevolgd. Via een 302 naar een intern adres springen zou de adrescontrole via een tweede route doorbreken.
Automatische stillegging — Na 10 opeenvolgende uitgeputte afleveringen. Een 410, een onveilig doel en het intrekken van de gekoppelde integratiesleutel leggen ONMIDDELLIJK stil.
alleen https, alleen poorten 443/8443, ingebedde inloggegevens (https://user:pass@…) worden geweigerd;
localhost, namen met één label en interne achtervoegsels zoals .internal / .local / .svc worden geweigerd — de intentie wordt geweigerd nog voordat naar het resolutieresultaat wordt gekeken, dus split-horizon-DNS kan de controle niet doorbreken;
IP-literals en ALLE records van de DNS-resolutie moeten publiek zijn. Resolveert een naam naar zowel een publiek als een privéadres, dan vraagt niemand ons welke we moeten kiezen → de naam wordt meteen geweigerd;
bij de aflevering wordt het adres één keer geresolved en wordt de verbinding vastgepind op het geverifieerde adres: het venster voor DNS-rebinding is gesloten;
de response-BODY van de ontvanger wordt nergens opgeslagen (alleen statuscode, duur en een korte fouttag) — dus het "lees"-pad, waaraan een gat in de adrescontrole in de praktijk zijn waarde ontleent, blijft dicht.
Er is bewust GEEN configuratieschakelaar om "privéadressen toe te staan": zo'n schakelaar blijft op een dag per ongeluk aan staan.
Slechts ÉÉN keer teruggegeven, alleen wanneer het abonnement wordt aangemaakt en bij rotate-secret. Het wordt versleuteld op de server opgeslagen en kan nooit worden teruggelezen; er is geen "opnieuw tonen".
lg drukt het af op het scherm en laat het daar — het schrijft het naar geen enkel configuratie- of cachebestand.
Ben je het kwijt, dan roteer je het; de oude waarde werkt OP DAT MOMENT niet meer. Voor een naadloze overgang moet je ontvanger tijdens de overgang beide secrets proberen.
Het adres wijzigen raakt het secret NIET: routineonderhoud zoals "de URL is verhuisd" mag de verificatie aan de ontvangende kant niet breken.
Gezondheid en status: niemand zou een stille koppeling eerder moeten opmerken dan jij
Een integratiekoppeling sterft zelden met veel lawaai. Meestal wordt ze stil in de kleine uurtjes: een token verloopt, de persoon namens wie de sleutel draait, verlaat het team, een scope wordt versmald, of het ontvangende endpoint begint 403 terug te geven. Wie het als eerste merkt, is bijna altijd de klant. lg status bestaat om die volgorde om te draaien.
Eén commando beantwoordt twee vragen tegelijk, omdat tijdens een storing beide op hetzelfde moment worden gesteld: is het platform in de lucht, en is mijn koppeling gezond. De platformregel werkt zonder token — tijdens een storing is het token zelf de eerste verdachte, en de statusvraag daaraan koppelen zou je zonder antwoord laten precies wanneer je er een nodig hebt.
De gezondheidssamenvatting houdt geen nieuw logboek bij; ze vat drie bestaande bronnen samen in één zin: de dagelijkse gebruiksteller (hoeveel je hebt aangeroepen en hoeveel er mislukte), het verzoekenlogboek (welk verzoek, wanneer, en waarom het werd geweigerd) en het afleveringslogboek van de uitgaande webhooks (heeft het event de ontvanger bereikt). Het foutpercentage wordt altijd uit de dagelijkse teller gelezen; het detaillogboek is begrensd en zegt dat duidelijk wanneer de grens is bereikt.
Dezelfde samenvatting verschijnt in het paneel: onder Settings › Integration › Keys heeft elke rij een badge met daaronder de reden. Drempels worden niet aan de clientkant berekend; welk niveau de server ook toekent, dat tonen zowel het paneel als lg status, zodat de twee schermen nooit verschillende dingen over dezelfde sleutel kunnen zeggen.
Je watchdog heeft geen token nodig. Het endpoint geeft alleen statuswoorden terug; het bevat geen versie, hostnaam, wachtrijnaam, aantal jobs, fouttekst of klantgegevens — en dat kan het ook niet.
De gezondheidssamenvatting wordt met een constant aantal queries per verzoek geproduceerd; het aantal queries groeit niet met het aantal sleutels. Lees voor details de recente verzoeken van die sleutel met lg logs en de uitgaande koppeling met lg webhooks list.
GEZOND — Geen gemeten fout en we hebben bewijs van succes: een geslaagde aanroep in het logboek, of verkeer dat in de teller foutloos bleef.
AANDACHT — Er begint iets te haperen: het foutpercentage of de reeks opeenvolgende mislukkingen heeft een drempel overschreden, verzoeken worden bij de controle geweigerd, de sleutel verloopt binnenkort, of een koppeling die regelmatig van zich liet horen, is stil geworden.
FALEND — De koppeling werkt op dit moment niet: het token werd onbedoeld ingetrokken, een gesloten sleutel wordt nog steeds aangeroepen, er zijn vijf mislukkingen op rij, het foutpercentage ligt boven vijftig procent, of een webhookabonnement werd stilgelegd.
GESLOTEN — De sleutel werd bewust gesloten en niemand roept hem aan. Dat is een beslissing, geen fout — en hij wordt niet rood gekleurd.
GEEN DATA — Er is geen meting: de sleutel is nooit aangeroepen, of de meting zelf is mislukt. Geen van beide is groen.
Geen vals groen. De badge Gezond vereist gemeten bewijs van succes; een sleutel die nooit is aangeroepen, wordt nooit groen, omdat geen enkele meting laat zien dat hij werkt.
Geen vals rood. Sleutels die je bewust hebt gesloten, worden getoond als Gesloten. Alles rood kleuren maakt rood betekenisloos; een gesloten sleutel wordt alleen rood als hij na het sluiten nog wordt aangeroepen — en dan is er echt een koppeling kapot.
Niet kunnen meten is niet hetzelfde als geen data. Mislukt een query aan de serverkant, dan toont de rij niet stilletjes nul; ze zegt dat de meting niet kon worden uitgevoerd.
Stilte wordt altijd gemeld, maar nooit blind omgezet in een waarschuwing. Een koppeling voor de maandafsluiting die dertig uur stil is, is normaal; een koppeling die op minstens vijf van de laatste zeven dagen van zich liet horen en stil wordt, is een fout. Het ritme wordt gemeten, niet aangenomen.
De statusquery zelf vervuilt de gezondheidscijfers niet. Aanroepen van lg status verschijnen in het verzoekenlogboek, maar worden buiten de gezondheidsberekening gehouden — anders zou je eigen geslaagde statusquery de reeks mislukkingen resetten en precies de fout verbergen die het scherm moet laten zien.
Elke regel wordt gemeten: er wordt een echte query op de database uitgevoerd, de commandocatalogus wordt echt opgebouwd, het live record van de queue worker wordt echt gelezen. Er wordt niets aangenomen.
Het antwoord zelf is ook een meting: als je de body kunt lezen, is de weblaag in de lucht.
Het hoogste niveau wordt alleen afgeleid van vereiste componenten. Stopt de wachtrij, dan is het antwoord degraded, niet down — een synchrone API-aanroep heeft de wachtrij niet nodig, en het platform down verklaren zou een vals alarm zijn.
Als de toestand van de wachtrij niet kan worden gemeten, blijft het hoogste niveau intact: iets niet weten is niet hetzelfde als meten dat er iets kapot is.
Ligt het platform plat, dan geeft het endpoint HTTP 503 terug. De body is envelopvrij, zodat monitoringtools kunnen alarmeren zonder hem te parseren, en het antwoord wordt nooit in een cache opgeslagen.
Fouten en exitcodes
Waar een machine op vertakt, is een stabiele string. De tekst in het veld error is bedoeld voor een mens, is gelokaliseerd en verandert zonder aankondiging — een integratie die op berichttekst vertakt, wordt niet ondersteund, en als ze breekt, is dat geen bug.
Twee taxonomieën, twee velden. error_code is de transportlaag (de tabel hierboven) en is waar je eerst op vertakt. error_key is de stabiele bedrijfsregelsleutel binnen failed — INSUFFICIENT_CREDITS, NOT_FOUND, DUPLICATE_CONTACT, INSUFFICIENT_STOCK — gepubliceerd als woordenboek in de catalogus (error_keys) en hieronder. Een commando dat nog geen sleutel afgeeft, geeft error_key: null terug; behandel een sleutel die niet in het woordenboek staat als een generieke fout.
ok — HTTP 200 · error_code — · CLI 0 · —
replayed — HTTP 200 · error_code — · CLI 0 · Idempotente replay; het werk is NIET opnieuw uitgevoerd.
failed — HTTP 422 · error_code failed · CLI 1 · Nee — een bedrijfsregel heeft het afgewezen (zie error_key). Zinloos zolang het argument niet verandert.
idempotency_conflict — HTTP 409 · error_code idempotency_conflict · CLI 2 · Nee — de sleutel werd eerst voor een ander commando gebruikt (conflicting_command). Maak een nieuwe sleutel aan.
forbidden — HTTP 403 · error_code forbidden · CLI 3 · Nee — rolcontrole, of een sleutel met leesscope bij een schrijvend commando.
(schema) — HTTP 422 · error_code invalid_request · CLI 2 · Nee — de request body of een argument is niet door de schemavalidatie gekomen (errors{}); geen bedrijfsregel.
server_error — HTTP 500 · error_code server_error · CLI 6 · Ja — exponential backoff met DEZELFDE idempotency key; de sleutel werd niet vergrendeld.
401 unauthenticated — Het token is verlopen of ingetrokken. Opnieuw proberen helpt niet; het token moet worden vervangen.
429 rate_limited — Rate limit bereikt voor dit token. Het antwoord bevat altijd Retry-After en een body met retry_after, limit en bucket; respecteer dat in plaats van een vaste vertraging te verzinnen. lg wacht en probeert het tot drie keer opnieuw, en stopt daarna met exitcode 5.
5xx server_error / netwerkfout — Probeer opnieuw met exponential backoff en DEZELFDE idempotency key. De sleutel wijzigen voert werk opnieuw uit dat de server misschien al heeft afgerond. lg probeert drie keer opnieuw (1 s, 2 s, 4 s) en stopt daarna met exitcode 6 en error_code network_error of server_error.
Stabiliteitsbelofte
De duurste vraag in een integratiecontract is “draait de code die ik vandaag schrijf morgen nog?” Eén getal beantwoordt die: contract_version in de catalogus, en de header X-Contract-Version bij elk antwoord. Het beantwoordt precies één vraag — draait eerder geschreven code nog ongewijzigd? Als het getal niet is gestegen: ja. Als het wel is gestegen: nee — iets waarop je vertrouwde, is verwijderd of versmald.
Omdat een aankondiging niets verwijdert: je bestaande code draait de dag erna precies zoals ervoor. Bij een aankondiging de versie verhogen zou twee signalen geven voor één wijziging en je leren het eerste te negeren — waardoor het signaal dat er echt toe doet, verzwakt. De aankondiging reist al mee met de aanroep die je doet: deprecated_at en replaced_by op de catalogusrij, een header X-Deprecated plus een blok deprecated in het antwoord van dat commando, en een stderr-waarschuwing van één regel als je lg gebruikt. Je hoeft niets te doen om te weten dat er iets verdwijnt; het staat al in je log.
Tussen aankondiging en verwijdering liggen minstens twee kalenderkwartalen. Gedurende het hele venster antwoordt het oude commando nog, en waarschuwt het bij elke aanroep. Wanneer een CLI-naam wordt uitgefaseerd, neemt zijn opvolger die naam over als alias: tijdens het venster bereikt de oude naam het oude commando, en op de dag dat het wordt verwijderd, komt dezelfde aanroep bij het nieuwe terecht — zonder dat jij een client-release hoeft uit te brengen.
preview_invoice → get_invoice (aangekondigd op 3 september 2026). get_invoice geeft hetzelfde previewblok terug en voegt de regelitems, de uitsplitsing van de belasting, geregistreerde betalingen, het resterende saldo en adressering via je eigen ERP-sleutel (external_ref) toe. preview_invoice blijft werken, net als lg invoices preview — ze waarschuwen allebei.
geen wijziging — Een nieuw commando · een nieuwe OPTIONELE parameter · een nieuw antwoordveld · een nieuwe foutsleutel · een nieuw endpoint — Niets doen. Je moet velden negeren die je niet kent; een parser die faalt op een onbekend veld, voldoet niet aan het contract.
geen wijziging — Een AANKONDIGING van uitfasering: melding dat een commando gaat verdwijnen — Je code blijft draaien. Zet een taak in je agenda — het venster is minstens 6 maanden.
stijgt — Een commando verwijderen · een oude CLI-naam uitfaseren · een antwoordveld laten vallen · een optionele parameter verplicht maken · een enum versmallen — Het betekent dat je het venster hebt gemist; de melding heeft je op drie verschillende plekken bereikt.
De API-naam van een commando (zoals list_loads) is voor altijd bevroren; dat is de naam die je in HTTP-aanroepen gebruikt.
error_code (transport) en error_key (bedrijfsregel) zijn stabiele strings. Er kunnen nieuwe verschijnen — behandel een sleutel die je niet in het woordenboek vindt als een generieke fout, niet als een breuk.
De koppeling tussen de HTTP-status en het veld status in de body ligt vast.
Het versienummer daalt nooit en is bij elk antwoord leesbaar — ook bij 304 en 429 zonder body.
De TEKST van fouten en beschrijvingen. Die is gelokaliseerd en verandert zonder aankondiging; vertakken op berichttekst wordt niet ondersteund.
De afwezigheid van velden die je niet kent. Een veld toevoegen verhoogt de versie niet.
Auto-increment-id's als bedrijfssleutels. Draag je eigen sleutel mee met external_ref.
Dynamische foutsleutels die zijn afgeleid van klassenamen; die maken geen deel uit van het contract.
Identiteitstabel van de commando's
De tabel hieronder is niet met de hand geschreven: hij wordt telkens wanneer deze pagina wordt geserveerd, gegenereerd uit het live commandoregister. Een commando dat op de server wordt toegevoegd, verschijnt hier vanzelf. De kolom "Poort" vertelt je of een commando om bevestiging vraagt en of het effect ongedaan kan worden gemaakt; de kolom "Rollen" vertelt je welke accounttypes het in hun catalogus zullen vinden. Badges markeren de commando's die een sleutel op managerniveau nodig hebben, de commando's die een bestand aannemen en de commando's die alleen vanuit lg draaien.
De opdrachten zijn per functie gegroepeerd, elk op een eigen pagina. Kies een functie om de opdrachtentabel te openen.
De API-naam (list_loads) is bevroren en zal niet veranderen; het is de naam die je in HTTP-aanroepen gebruikt. De CLI-identiteit (loads list) valt onder het versiebeleid: eenmaal aangekondigd verandert ze alleen met een versieverhoging en een migratievenster, waarin de catalogus het oude paar als alias serveert. De beschrijvingen hier komen uit het eigen record van elk commando en zijn ingekort — lees voor de volledige tekst, de parametertypes en de enum-waarden het catalogus-endpoint of voer lg help uit. Commando's die alleen voor affiliates zijn, staan hier niet; een affiliate-account ziet ze in zijn eigen catalogus.
Zendingen en tracking — Zendingen aanmaken, betrokken partijen, documenten, trackinglinks, afleverhandtekening, ETA en uitzonderingen. 115 opdrachten — /nl/developers/cli/loads
Grens en douane — Controle van grensgereedheid, wachttijden aan grenzen en in havens, exportdocumenten, U-ETDS-melding. 42 opdrachten — /nl/developers/cli/border
Aanvragen en offertes — Transportaanvragen openen, offertes vragen en uitbrengen, aanbestedingen, vervoerders in uw netwerk. 42 opdrachten — /nl/developers/cli/quotes
Tariefkaarten en verkoopoffertes — Afgesproken tariefkaarten, de offertewaterval en verkoopoffertes aan uw klanten. 57 opdrachten — /nl/developers/cli/pricing
Vloot en chauffeurs — Chauffeurs, voertuigen, onkostenbonnen, chauffeursrekeningen, ritplanning en Schengendagen. 115 opdrachten — /nl/developers/cli/fleet
Magazijn en voorraad — Magazijnen, reserveringen, dockafspraken, poortscherm, producten, voorraad en pallets. 69 opdrachten — /nl/developers/cli/warehouse
Boekhouding en facturatie — Facturen, controle van inkoopfacturen, Paraşüt, journaalposten, ontvangsten en betalingen, marges. 95 opdrachten — /nl/developers/cli/finance
Berichten en e-mail — Zendingschats, directe berichten, e-mailconcepten en postvakken, meldingen. 58 opdrachten — /nl/developers/cli/messages
Bedrijven en team — Bedrijvenlijst, relaties en documenten, dochterbedrijven, teamleden en uitnodigingen. 65 opdrachten — /nl/developers/cli/contacts
Automatisering en rapporten — Automatiseringsregels, eigen rapporten, Excel- en pdf-bestanden, werkplannen. 27 opdrachten — /nl/developers/cli/automation
Account en integratie — Account- en taalinstellingen, integratiesleutels, pakket, tegoed en portemonnee. 16 opdrachten — /nl/developers/cli/account
ERP- en CRM-integratie — Identiteit: geen serviceaccounts, maar een echte gebruiker
Een ERP of CRM maakt verbinding met Logistivo als een echte bedrijfsgebruiker met een persoonlijk access token dat in het paneel is aangemaakt. Een synthetisch serviceaccount — zonder bedrijf, vrijgesteld van scoping, zonder iemand die ervoor verantwoordelijk is — wordt nooit aangemaakt.
Dit is architectuur, geen voorkeur. Multi-tenant-isolatie rust volledig op het bedrijf van de gebruiker; voor een identiteit zonder bedrijf wordt de isolatiescope inert, en één verkeerde query met dat token leest gegevens die er niet bij horen. De tweede reden is audit: de gebruikerskolom in het logboek koppelt "wie heeft dit uitgevoerd" aan een persoon; een serviceaccount maakt die kolom betekenisloos en laat een integratie die facturen uitgeeft zonder eigenaar achter. De derde is intrekking: als een token bij een persoon hoort, valt de integratie stil wanneer die persoon vertrekt. Een koppeling zonder eigenaar is de koppeling die jarenlang stilletjes blijft schrijven.
In de praktijk: het bedrijf maakt in het paneel een normale gebruiker aan (bijvoorbeeld "ERP-koppeling", in eigendom van een met naam genoemde medewerker), geeft die een beperkte rol, maakt een token aan vanuit de sessie van die gebruiker en zet het in het ERP.
Die gebruiker is zichtbaar in het rechtensysteem, zijn rechten kunnen worden ingeperkt en zijn token kan afzonderlijk worden ingetrokken. Wat verboden is, is niet een account aanmaken — het is een account aanmaken dat niet aan een tenant gebonden is.
Eén integratie per token. Delen twee systemen een token, dan is de granulariteit van intrekking weg: het CRM afsluiten betekent ook het ERP afsluiten.
ERP- en CRM-integratie — Versiebeheer en uitfasering
Het catalogusantwoord bevat een integer contract_version; commandorijen bevatten since, deprecated_at en replaced_by. De contractversie stijgt alleen bij brekende wijzigingen.
De versie stijgt NIET bij: een nieuw commando, een nieuwe optionele parameter, een nieuw veld in een antwoord. Een consument moet velden negeren die hij niet kent; een client die een fout geeft op een onbekend veld, voldoet niet aan het contract.
De versie stijgt WEL bij: een commando verwijderen of hernoemen, een antwoordveld verwijderen, een optionele parameter verplicht maken, een enum versmallen. De oude vorm blijft minstens twee kalenderkwartalen (6 maanden) in leven met deprecated_at en replaced_by.
Uitfasering wordt aangekondigd in de catalogus, niet alleen in een changelog. Omdat de client zichzelf uit de catalogus opbouwt, drukt een commando met een ingestelde deprecated_at een waarschuwing af zonder enige client-release, en de integrator ziet die in zijn logs.
De API-naam is voor altijd bevroren. De CLI-identiteit (domain/verb) kon vóór de aankondiging vrij opnieuw worden ingedeeld; na de aankondiging verandert ze alleen met een versieverhoging en een migratievenster, waarin het oude paar als alias wordt geserveerd.
In de praktijk: het catalogusantwoord en de header X-Contract-Version dragen de versie; elke commandorij draagt since, deprecated_at, replaced_by en aliases (oude domain/verb-paren). Een verouderd commando aanroepen werkt nog steeds en antwoordt met een header X-Deprecated: name; deprecated_at=…; replaced_by=… plus een object deprecated in de body. ?domain= op de catalogus zet een oud aliasdomein om naar het huidige commando.
Een client die versie 1 begrijpt en een hoger getal tegenkomt, moet een waarschuwing loggen en doorgaan; lg doet precies dat. De uitfaseringen die van kracht zijn, staan in de stabiliteitsbelofte hierboven.
ERP- en CRM-integratie — Stabiele identifiers: geef je ERP nooit een auto-increment-id als sleutel
Interne auto-increment-id's zijn ondoorzichtig en gebonden aan de tenant: de geldige id van een ander bedrijf geeft jou "niet gevonden", geen data. Maar ondoorzichtig zijn maakt ze nog geen bedrijfssleutels. Wat een ERP in zijn eigen record opslaat, moet een bedrijfssleutel zijn.
Lading: code (de klantcode, bijv. FSK2158). loads get werkt al op code.
Land: ISO 3166-1 alpha-2. countries search geeft de code terug.
HS / tarief: de code zelf — de nomenclatuur is al universeel.
Factuur: het factuurnummer, zodra de factuur is uitgegeven. Een concept heeft alleen een surface-id, en een concept-id is GEEN bedrijfssleutel — het ERP moet zijn eigen referentie meedragen en nooit een concept-id opslaan.
Product, magazijn, contact: vandaag alleen een surface-id. De regel voor nieuwe commando's is expliciet: elk commando dat een surface-id teruggeeft, geeft ook de eigen bedrijfssleutel van de tenant terug (SKU, code, belastingnummer), zodat het ERP aan zijn kant kan matchen.
ERP- en CRM-integratie — Paginering, filtering en incrementele sync
Lijstcommando's nemen limit aan en geven count terug. Voor een nachtelijke sync verbindt het contract zich aan het volgende; een lijstcommando dat het heeft overgenomen, kondigt cursor en updated_since aan in zijn JSON Schema, en zolang dat niet zo is, behandel je het als een klein venster (maximaal 20 rijen, geen cursor).
Verzoek: limit (1..het maximum per commando) plus cursor (ondoorzichtig, alleen vooruit, ondertekend door de server). offset wordt NIET gebruikt — in een live tabel verschuift een offset; een record dat tussen twee pagina's wordt ingevoegd, laat het ERP een rij overslaan of dubbel tellen, en dat gebeurt stilzwijgend.
Antwoord: { count, total?, next_cursor|null }. count is het aantal rijen in dit antwoord; wanneer next_cursor null is, is de lijst compleet. Geef next_cursor ongewijzigd terug — het is geen paginanummer en het is niet aan jou om het op te bouwen.
Een gemanipuleerde of vreemde cursor wordt geweigerd met 422 invalid_request; een cursor is gebonden aan het bedrijf dat hem ontving en kan geen gegevens van een andere tenant pagineren.
Filteren: de benoemde parameters in het JSON Schema, gecombineerd met AND. Er is geen vrije querytaal — een DSL zou een tweede queryoppervlak zijn dat we zouden moeten verdedigen.
Incrementele sync: updated_since (ISO-8601, UTC) plus de cursor. Sla de nieuwste updated_at op die je hebt gezien en geef die bij de volgende run terug; zonder dat haalt elk ERP elk uur alles opnieuw op.
Externe referentie: schrijvende commando's accepteren external_ref (je eigen documentsleutel), uniek per bedrijf; een tweede create met dezelfde external_ref wordt geweigerd in plaats van gedupliceerd, en list/get geven hem terug, zodat je records aan jouw kant kunt matchen.
ERP- en CRM-integratie — Rate limits
De sleutel voor de limiet is het token, niet het IP-adres: een ERP komt van achter één NAT, en een limiet op IP zou een heel bedrijf als één gebruiker tellen. Twee integraties met twee sleutels eten nooit elkaars quota op — de tweede reden voor "één integratie per sleutel".
Discovery zonder authenticatie (public/cli/catalog): 30 per minuut. Het is een woordenboek, geen databron; lees het één keer tijdens het schrijven van je koppeling, nooit in een productielus.
Catalogus-endpoints (GET common/commands, GET common/commands/{name}): 120 per minuut per token. De catalogus verandert zelden en antwoordt 304 op If-None-Match; haal hem niet vóór elk commando opnieuw op — lg cachet hem een uur.
Leescommando's (POST common/commands/{name} met read_only: true): 120 per minuut per token.
Schrijvende commando's (POST common/commands/{name} met read_only: false; ook een onbekende naam telt hier mee): 30 per minuut per token. Schrijfacties hebben bijwerkingen; een op hol geslagen lus wordt in rekening gebracht.
Commando's die credits verbruiken (credit_cost in de catalogusrij is niet nul — bijvoorbeeld tariffs inquiry en export-documents generate): de echte limiet zijn de CREDITS, niet het aantal verzoeken. Een antwoord 200 kan een credit hebben gekost.
Dagelijkse maxima per bedrijf, gedeeld met het paneel: commando's die e-mail of push sturen naar mensen buiten je bedrijf putten uit 300 uitgaande meldingen per dag, en het starten van betaalde container- of scheepstracking uit 100 per dag. Boven het maximum antwoordt een commando met DAILY_LIMIT_REACHED en retry_after; bestandsuploads hebben hun eigen maxima (zie Commando's die bestanden aannemen).
429 bevat altijd Retry-After en een body { error_code: "rate_limited", retry_after, limit, bucket }; respecteer dat in plaats van een vaste vertraging te verzinnen. De catalogus publiceert de actuele getallen onder rate_limits.
ERP- en CRM-integratie — Wat we niet zullen doen
Dit is vaak het nuttigste deel van een contract: als je weet wat er nooit komt, kun je eromheen ontwerpen.
Geen serviceaccount en geen principal die niet aan een tenant gebonden is.
Geen betaling, kaartnummer of juridische toestemming via de API of een chat. Die stappen blijven in de browser van de persoon; een commando geeft je de link.
Geen tweede pad: er is geen directe databasetoegang, geen shelltoegang en geen bulk-endpoint dat het enige handhavingspunt omzeilt. De rolcontrole, de bevestigingspoort, idempotency en het auditlogboek worden alleen daar gehandhaafd.
Vertakken op de tekst van foutmeldingen wordt niet ondersteund; de tekst is gelokaliseerd en verandert zonder aankondiging.
Geen offset-paginering.
Een surface-id als bedrijfssleutel in je ERP gebruiken wordt niet ondersteund.
Uitgaande webhooks worden niet in dit contract geperst — maar ze BESTAAN nu en zijn op deze pagina gedocumenteerd (de webhooksectie hierboven). De catalogus is een PULL-oppervlak en de eventstroom is een APART contract: eventnamen en het payloadschema worden volgens hun eigen regels geversioneerd en zijn niet gekoppeld aan de contractversie van de commandocatalogus.
De machineleesbare catalogus
Deze pagina is geschreven voor mensen. Voor een AI-assistent of een geautomatiseerde client bestaat dezelfde informatie als een gestructureerde kopie zonder authenticatie.
GET /api/public/cli/catalog vereist geen authenticatie en geeft de publieke identiteit van de commando's terug: de bevroren API-naam, de CLI-identiteit domain/verb, de beschrijving, de JSON Schema-parameters, de vlaggen read_only, confirmation_needed en irreversible, de credit_cost, en de toegangsvelden key_level, permission, file_params, secret_parameters en cli_only. Het geeft geen persoonsgegevens, geen tenantgegevens en geen voorbeeldrecords terug — alleen wat het oppervlak is.
De juiste manier waarop een externe agent het gebruikt: lees de catalogus, leg in JE EIGEN woorden uit welke taken mogelijk zijn, en verwijs de gebruiker, wanneer uitvoering nodig is, naar het uitvoeren in zijn eigen omgeving met zijn eigen token. De agent vraagt nooit om het token van een gebruiker, genereert het niet en geeft het niet door.
Logistivo koppelen aan een AI-assistent voor aanmelding en vrachtaanvragen is een apart kanaal met een eigen pagina:
De catalogus is zonder authenticatie; uitvoering niet. Er is geen manier om een commando namens een agent uit te voeren — wat er draait, is altijd de eigen identiteit van de gebruiker.
Een Logistivo-wachtwoord, verificatiecode of access token gaat nooit door een chat. Bouw geen flow die erom vraagt, er een genereert of er een doorgeeft.
Of een commando onomkeerbaar is, staat in de catalogus. Stel nooit "laten we het proberen" voor bij een commando met irreversible: true.
Commando's waarvan de credit_cost niet nul is (bijvoorbeeld tariffs inquiry en export-documents generate), hebben een monetair resultaat; roep ze niet aan in een geautomatiseerde lus.
Betalingen, kaartnummers en juridische toestemming gaan nooit via een chat of een agent. Bied in plaats daarvan de link van handoff-links generate aan; de persoon rondt de stap af in zijn eigen browser.
Een agent die met de sleutel van een gebruiker handelt, moet eerst users get aanroepen: dat geeft de rol, het toegangsniveau van de sleutel, de effectieve rechten en of een openstaande toestemming of telefoonverificatie schrijfacties blokkeert — voorspel weigeringen in plaats van ze te verzamelen.
Een platte-teksttweeling van deze pagina staat op /cli.md; gebruik die als je markdown betrouwbaarder parseert dan HTML.
De machineleesbare definitie: OpenAPI 3.1 en Postman
De catalogus hierboven is het eigen formaat van Logistivo. Dezelfde informatie wordt ook gepubliceerd in twee industriestandaarden die je tools al begrijpen: een OpenAPI 3.1-definitie en een Postman-collectie. Geen van beide is met de hand geschreven — beide worden bij elk verzoek gegenereerd uit het live commandoregister, dus ze kunnen niet verouderen.
De definitie IS de catalogus, geen tweede werkelijkheid. Elk commando verschijnt als een operatie POST /api/common/commands/; het body-schema is het eigen JSON Schema van het commando (byte voor byte wat de assistent ziet), het antwoordschema is de gedeelde envelop, de poortvlaggen (read_only, confirmation_needed, irreversible en de creditbadge) staan in de extensie x-logistivo, en de zakelijke foutsleutels staan onder x-error-keys. Een uitgefaseerd commando wordt gemarkeerd met deprecated: true en blijft gedurende zijn venster van zes maanden aanroepbaar.
Naast het commando-oppervlak staan ook de REST-endpoints die het integratiecontract dragen in de definitie: 10 lijst-endpoints met incrementele sync (updated_since + cursor + limit) en 7 schrijf-endpoints die je eigen sleutel accepteren (external_ref). Het REST-oppervlak van Logistivo is veel groter dan dat; de rest is MET OPZET weggelaten. Die payloads zijn het eigen contract van het product, en een schema dat op gissingen is gebaseerd, zou je gegenereerde client bij de eerste aanroep breken — en je zou de bug in jouw code zoeken, niet in de onze.
De definitie wordt gegenereerd voor de ROL van degene die erom vraagt: het commando van een andere rol komt nooit in het document, omdat een definitie een contract is en geen woordenboek, en alles erin met dat token aanroepbaar moet zijn. De versie zonder authenticatie is de vereniging van de drie rollen, en daar vermeldt elke operatie onder x-logistivo.roles welke rollen haar zien.
Geloof ons niet op ons woord — controleer het zelf: npx @redocly/cli lint logistivo-openapi.json slaagt met nul waarschuwingen.
GET /api/common/spec/openapi.json — De OpenAPI 3.1-definitie voor de rol van je token. Bevat een ETag; If-None-Match geeft je een 304, zodat je hem niet bij elke build opnieuw downloadt.
GET /api/common/spec/postman.json — Dezelfde scope als een Postman v2.1-collectie, met de variabelen base_url en token en mappen die al per commandodomein zijn gegroepeerd.
GET /api/public/cli/openapi.json — De versie zonder authenticatie — de vereniging van de drie rollen. Om de koppeling te ontwerpen en de kosten in te schatten voordat je een token hebt.
GET /api/public/cli/postman.json — De Postman-collectie zonder authenticatie: één bestand dat je aan je team kunt geven.
761 operaties — 721 commando's + 36 REST- en control-plane-operaties + 4 catalogus- en identiteitsendpoints. De getallen op deze pagina worden niet met de hand getypt; ze worden bij elk verzoek uit het live document geteld, dus op de dag dat een commando live gaat, stijgen ze hier ook — en de optelling klopt.
Het beveiligingsschema — bearerAuth: een Passport-token dat voor een echte gebruiker is uitgegeven. Een sleutel met leesscope mag alleen operaties aanroepen die gemarkeerd zijn met x-logistivo.read_only: true; een schrijfpoging geeft 403 VÓÓR de bevestigingspoort, dus een alleen-lezen-sleutel ziet nooit een 409.
Elke foutvertakking is uitgeschreven — Elke operatie beschrijft 401/403/404/409/422/429/500 afzonderlijk. De twee betekenissen van 409 (bevestiging vereist / idempotency-conflict) en de twee betekenissen van 422 (schemafout / zakelijke afwijzing) zijn in het document gescheiden, zodat je generator ze niet samenvoegt in één vertakking.
Geen tijdstempel — Het document bevat geen generatietijd. Dezelfde catalogus levert dezelfde bytes op, en daarom werkt de ETag echt en ziet een definitie die je in versiebeheer commit er niet bij elke download 'gewijzigd' uit.
We hebben geen productpayloads verzonnen — Bij REST-schrijf-endpoints wordt alleen het contractveld (external_ref) beschreven; de rest van de body blijft open als additionalProperties: true en de lezer wordt naar de productdocumentatie verwezen. Een definitie die onvolledig maar waar is, wint het van een die volledig maar verzonnen is.
De lijst met foutsleutels per operatie is NIET uitputtend — x-error-keys noemt alleen de sleutels die met zekerheid volgen uit het eigen record van het commando, en zegt dat met x-error-keys-exhaustive: false. Het volledige woordenboek staat in de root van het document; behandel elke sleutel die je niet herkent als een generieke fout. Een verzonnen 'volledige lijst' zou je ertoe hebben gebracht nooit de standaardvertakking te schrijven.
Discovery-tools zitten niet in de definitie — search_commands, run_command en list_capabilities bestaan alleen binnen de chatlus en kunnen niet via HTTP worden aangeroepen. Als ze waren opgenomen, zou je generator drie methoden hebben geschreven die nooit zouden kunnen werken.
Codegeneratie: een getypeerde client uit de definitie
Je hebt de definitie; genereer er nu werkende code uit. `lg codegen` leest het OpenAPI-document en schrijft een client van één bestand zonder afhankelijkheden — TypeScript (typedeclaraties plus een dunne wrapper voor aanroepen) of PHP (een clientklasse met PHPDoc-array shapes). Geen `npm install`, geen composer: `fetch` aan de TypeScript-kant, `ext-curl` aan de PHP-kant.
De generatie gebeurt op JOUW machine, niet op onze server. Dat is geen voorkeur: pin de definitie één keer vast in je repository (`lg spec --out=...`) en hetzelfde commando draait bij elke build zonder netwerk en zonder token, zodat je CI nooit afhankelijk is van onze uptime. En omdat de gegenereerde code code is die in je ERP DRAAIT, zorgt het bewaren ervan in je repository, in plaats van het ophalen via een API, ervoor dat elke wijziging zichtbaar wordt in `git diff`.
De gegenereerde client behandelt alle drie Logistivo-sporen correct, en hij leert welk spoor welk is uit het document in plaats van te gokken: elke operatie declareert haar spoor in `x-logistivo.surface`. Het commandospoor pakt de envelop `{success, data:{…}}` uit; een REST-synclijst heeft GEEN envelop en wordt teruggegeven zoals hij is (uitpakken zou `next_cursor` laten wegvallen); een REST-schrijfactie geeft de eigen productbody van het endpoint terug. Een generator voor algemeen gebruik kent dit onderscheid niet — de onze wel.
De types zijn geen giswerk: de argumentinterface van elk commando wordt gegenereerd uit precies het JSON Schema dat de assistent ziet. Verplicht blijft verplicht, enums worden union types, geneste objecten worden geneste types. In de praktijk: als de server een veld vereist, faalt de aanroep die het vergeet niet met een 422 in productie — hij faalt bij het compileren.
Er wordt geen generatietijdstempel in het bestand geschreven: dezelfde definitie met dezelfde vlaggen levert dezelfde bytes op. Opnieuw genereren maakt daardoor geen ruis in `git diff`, en het enige dat echt veranderd is — het contract — blijft zichtbaar.
1. Pin de definitie vast — De definitie wordt voor je rol gegenereerd; elke operatie erin is met dat token aanroepbaar. Commit het bestand. lg login --api-key= lg spec --out=logistivo-openapi.json
2. Genereer de client — Er komt één bestand uit, met ELKE operatie uit de definitie die je hebt vastgepind als methode: de commando's die je rol kan aanroepen, de REST-endpoints die het integratiecontract dragen, en de discovery-endpoints. Het aantal is dat van JOUW rol, niet het platformtotaal — vandaag levert een verladerssleutel 646 commandomethoden op, een vervoerder 621, een douane-expediteur 392. Genereer vanuit de publieke definitie zonder authenticatie en het maximum is 761 operaties. 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. Controleren, daarna gebruiken — Als de gegenereerde code niet compileert, ligt de fout bij ons, niet bij jou: de integriteit van de definitie wordt bewaakt door een uitvoerbare controle op de server. npx tsc --noEmit --strict --target ES2022 --module ESNext --moduleResolution bundler logistivo-client.ts php -l LogistivoClient.php
Eén methode per operatie — Elk commando in het document, elk REST-endpoint dat het integratiecontract draagt, en de discovery-endpoints. Genereer vanuit de definitie van je rol en je krijgt alleen wat je kunt aanroepen (646 commando's voor een verlader); genereer vanuit de publieke definitie en je krijgt alle 761 operaties. Op de dag dat er op de server een commando wordt toegevoegd, haalt opnieuw genereren het binnen; er is geen client-release om op te wachten.
Argumenttypes — Het `args`-schema van elk commando wordt een interface (een array shape in PHP). Verplichte velden blijven verplicht, enums worden unions. In TypeScript is een vergeten verplicht veld een compileerfout; in PHP zien je IDE en PHPStan dezelfde vorm.
Foutklassen — De transporttaxonomie (`error_code`) en de zakelijke taxonomie (`error_key`) zijn aparte velden; de bevestigingspoort en de rate limit zijn aparte fouttypes. De union van foutsleutels blijft open voor onbekende waarden — wanneer de server een nieuwe sleutel declareert, stopt je code niet met compileren, maar valt die sleutel in de vertakking `default`.
Een correct retrybeleid — Automatische retries gelden alleen voor veilige aanroepen: leesacties, en schrijfacties met een idempotency key. Een schrijfactie zonder sleutel die een timeout krijgt, betekent niet 'er is niets geschreven', dus de client herhaalt haar nooit blind. Bij een 429 wacht hij de `Retry-After` van de server af in plaats van een vertraging te verzinnen.
Resultaatbodies zijn niet getypeerd — Commandoresultaten komen terug als `unknown` (`mixed` in PHP), om dezelfde reden als in de definitie zelf: resultaatvormen zijn de zakelijke uitvoer van het commando, geen deel van het contract. Een gegokt resultaattype zou beginnen te liegen zodra er voor het eerst een veld verschuift.
Het gegenereerde bestand wordt niet met de hand bewerkt — Het is uitvoer, geen bron. Heb je extra gedrag nodig, wikkel dan de gegenereerde klasse in; alles wat je erin schrijft, gaat bij de volgende generatie verloren.
Discovery-tools worden niet gegenereerd — `search_commands`, `run_command` en `list_capabilities` leven alleen binnen de chatlus en kunnen niet via HTTP worden aangeroepen; ze ontbreken in de definitie en daarom ook in de client. Ze opnemen zou hebben betekend dat er drie methoden werden geschreven die nooit werken.
Eerlijke afbakening
We breiden deze sectie liever uit dan dat we haar inkrimpen. De waarde van een integratiecontract zit minder in wat het belooft dan in hoe duidelijk het zegt wat het niet doet.
De CLI draait in de context van een tenantgebruiker — Elk commando draait onder het bedrijf en de rol van de gebruiker wiens token wordt aangeboden. Een modus voor de platformbeheerder — een administratieve modus die over bedrijven heen leest — valt buiten dit oppervlak en wordt van hieruit niet opengesteld.
Je commandolijst hangt af van je rol — Een verladersaccount ziet 646 commando's, een vervoerder 621, een douane-expediteur 392, een affiliate 55. Ontbreekt er een commando in je catalogus, controleer dan eerst de rol; staat het erin maar wordt het geweigerd, controleer dan de scope en het toegangsniveau van de sleutel. Chauffeursaccounts hebben helemaal geen toegang tot dit oppervlak.
Sommige commando's verbruiken credits — Tariefaanvragen, documentgeneratie en een paar andere AI-gestuurde commando's putten uit het creditsaldo van je abonnement. Elke catalogusrij bevat credit_cost {mode, credits}: fixed is het exacte bedrag per aanroep, read_only kost nooit iets, en computed betekent dat de kosten van de aanroep afhangen — credits is dan null en het echte bedrag verschijnt op de bevestigingskaart. Een preflight (dry_run) vertelt je wat één aanroep zou kosten en of je saldo dat dekt.
Integratiesleutels kunnen de dashboardchat niet aansturen — De AI-assistent in het dashboard is voor mensen. Een run van de assistent starten of voortzetten met een integratiesleutel wordt geweigerd met 403; agents gebruiken de commando-endpoints, lg of het MCP-kanaal, waar elk commando op het toegangsniveau van de sleutel draait en de schrijfacties als integratieschrijfacties worden vastgelegd.
De catalogus vervangt de bestaande REST API niet — Het REST-oppervlak dat de web- en mobiele apps van Logistivo aandrijft, blijft waar het is en valt nog steeds onder de regel van achterwaartse compatibiliteit. De commandocatalogus vervangt resource-CRUD niet; hij is de laag van de WERKWOORDEN — de enige, geauditeerde manier om iets te doen.
Lijstcommando's geven vandaag kleine vensters terug — Zolang een lijstcommando cursor en updated_since niet in zijn schema aankondigt, is het maximum 20 rijen zonder cursor. Het is niet ontworpen om een volledige kopie van je gegevens te extraheren; incrementele sync wordt commando voor commando uitgerold.
Veelgestelde vragen
Waarvoor wordt de Logistivo CLI gebruikt?
Hij voert het werk in je Logistivo-account uit vanuit een terminal, een script of je eigen AI-agent: ladingen en ritten, aanvragen, biedingen en tenders, wagenpark, chauffeurs en hun onkosten, documenten, contacten en rekeningen-courant, facturen en boekhouding, magazijn en voorraad, teamleden, HS-tarieven en antidumpingrechten. Elke schrijfactie in het paneel heeft een commando; betalingen, juridische toestemming en het sluiten van een account blijven bewust in de browser. Dezelfde commando's zijn via HTTP aan te roepen voor ERP/CRM-integraties en via het MCP-kanaal.
Hoe worden commando's in de Logistivo CLI benoemd?
De vorm is lg --parameter=value. Het domein is een entiteit in het meervoud (loads, demands, invoices, export-documents) en het werkwoord komt uit een gesloten woordenschat die alleen door een bewuste beslissing groeit (list, get, create, update, search, set-status, generate enzovoort). Alle werkwoorden van één entiteit wonen in één domein, en het paar (domein, werkwoord) is uniek in de hele catalogus.
Hoe authenticeer ik me bij de CLI?
Interactief toont lg login een goedkeuringscode die je in je browser bevestigt nadat je bij Logistivo bent ingelogd — er wordt geen wachtwoord of sleutel in de terminal getypt, en de sessie blijft ingelogd en vernieuwt zichzelf totdat je lg logout uitvoert. lg login --password (e-mailadres en wachtwoord) blijft beschikbaar als terugvaloptie. Gebruik op servers en in CI een integratiesleutel die is uitgegeven in het paneel of met lg keys create: lg login --api-key slaat hem op in een lokaal profiel, of je zet hem in de omgevingsvariabele LOGISTIVO_TOKEN. Via HTTP reist het token mee in de header Authorization: Bearer.
Kan ik een serviceaccount aanmaken voor mijn ERP-integratie?
Nee. Een integratie maakt verbinding met het token van een echte bedrijfsgebruiker die in het paneel is aangemaakt. Een synthetische identiteit zonder bedrijf maakt multi-tenant-isolatie inert, maakt de kolom "wie heeft dit uitgevoerd" in het auditlogboek betekenisloos en laat een koppeling achter die niet stilvalt wanneer haar eigenaar vertrekt. Het juiste patroon is een speciale gebruiker met een beperkte rol en een met naam genoemde eigenaar.
Heeft Logistivo een testomgeving (sandbox)?
Ja, en die is selfservice: er wordt een aparte sandbox-tenant voor je bedrijf geopend — dezelfde code, dezelfde commandocatalogus, een eigen creditadministratie. De omgeving wordt afgeleid van het bedrijf van de sleutel en kan niet met het verzoek worden meegegeven; een aanroep met het verkeerde profiel stopt aan de serverkant met 403 ENVIRONMENT_MISMATCH. Een aanvraag die je in de sandbox opent, bereikt nooit echte vervoerders, een sandbox-event wordt nooit aan je live webhookabonnement afgeleverd, en je live saldo beweegt niet. Endpoints: POST /api/common/integration-sandbox (openen), POST /api/common/integration-sandbox/keys (sleutel), GET /api/common/integration-sandbox/go-live (go-live-checklist). Aan de kant van lg zijn lg --sandbox en lg --live profielkiezers voor één run.
Hoe lees ik de uitvoer van lg --json in een script?
De uitvoer is de hele HTTP-envelop: { "success": bool, "data": { "contract_version", "command", "status", "result" }, "code", "message" }. De zakelijke payload staat onder .data.result; bij lijstcommando's zijn de rijen .data.result., is het aantal .data.result.count en is de volgende pagina .data.result.next_cursor. Het juiste jq-pad ziet er dus uit als lg loads list --json | jq -r '.data.result.loads[].load_code'. Een pad dat de envelop overslaat, geeft geen fout, het geeft stilzwijgend null terug — in een watchdog-script wordt dat een alarm dat nooit ophoudt af te gaan. De enige uitzondering is /api/public/status, waarvan de body bewust envelopvrij is.
Als ik hetzelfde verzoek twee keer stuur, krijg ik dan dubbele records?
Niet als je een idempotency_key hebt meegestuurd. Een tweede aanroep met dezelfde sleutel voert het commando niet opnieuw uit; hij geeft het eerste resultaat terug met status replayed. De sleutel moet een UUID zijn en bij retries DEZELFDE blijven — per poging een nieuwe sleutel genereren is hetzelfde als geen idempotency gebruiken.
Wat doet --yes?
Het passeert de bevestigingspoort. Wanneer een bevestigingsplichtig commando zonder --yes wordt aangeroepen, verandert er niets: de server vat in één zin samen wat hij gaat doen, zegt of het onomkeerbaar is, en stopt (HTTP 409, CLI-exitcode 4). Het commando herhalen met --yes voert het werk uit.
Hoe detecteer ik een mislukt commando in een script?
Lees de exitcode, nooit de berichttekst: 0 succes, 1 afwijzing door een bedrijfsregel, 2 commando- of argumentfout, 3 authenticatie- of rolfout, 4 bevestiging vereist. Via HTTP zijn de equivalenten 200, 422, 404, 403 en 409, en het veld error_code in de body is stabiel. Het fout-BERICHT is gelokaliseerd en verandert zonder aankondiging.
Hoe ontdek ik de beschikbare commando's programmatisch?
GET /api/public/cli/catalog voor discovery zonder authenticatie, en GET /api/common/commands voor de lijst die je account daadwerkelijk kan zien. Beide geven per commando de JSON Schema-parameters terug; bouw je client daaruit op in plaats van een commandolijst hard te coderen.
Moet ik mijn client bijwerken wanneer er een nieuw commando wordt toegevoegd?
Nee. De client haalt zijn commandolijst uit de catalogus, dus een commando dat op de server wordt toegevoegd, verschijnt zonder nieuwe client-release. Een update is alleen nodig bij een brekende wijziging die de contractversie verhoogt, en in dat geval blijft de oude vorm minstens zes maanden in leven.
Vervangt de CLI de bestaande REST API?
Nee. Het REST-oppervlak dat de web- en mobiele apps aandrijft, blijft bestaan. De commandocatalogus vervangt resource-CRUD niet; hij is de laag van de werkwoorden — de enige manier om een actie uit te voeren met rolcontrole, bevestigingspoort en audit.
Hoe krijg ik een Logistivo-API-sleutel en wat kan die?
Een manager met het recht voor teambeheer geeft hem uit in het paneel onder Settings › Integration keys, of vanuit een terminal met lg keys create. De sleutel handelt namens een echt teamlid en heeft drie onafhankelijke instellingen: scope (read opent de catalogus en niet-schrijvende commando's, write opent elk commando — de bevestigingspoort blijft zoals ze is), optionele domeinrechten, en een toegangsniveau — employee, de standaard, voor dagelijkse operaties, of manager voor team, instellingen, sleutels en geld. Hij wordt één keer getoond en niet op de server opgeslagen; hij kan worden geroteerd, overgedragen en ingetrokken. Wanneer het lid namens wie hij handelt vertrekt, wordt ook de sleutel gesloten. Er is geen serviceaccount.
Wat gebeurt er als ik een idempotency key hergebruik voor een ander commando?
De server antwoordt 409 idempotency_conflict en noemt het commando waarvoor de sleutel eerst werd gebruikt; er draait niets en er wordt niets herhaald. Sleutels zijn beperkt tot je bedrijf, gebonden aan één commando en 24 uur vergrendeld — daarna start dezelfde sleutel een nieuwe uitvoering.
Hoe worden rate limits op mijn integratie toegepast?
Per token, per minuut, in drie buckets: catalogus lezen 120, leescommando's 120, schrijvende commando's 30. Een 429 bevat altijd Retry-After en een body met retry_after, limit en bucket; wacht zo lang en probeer het opnieuw. De catalogus publiceert de actuele getallen onder rate_limits.
Hoe onderscheid ik een zakelijke afwijzing van een transportfout?
Vertak eerst op error_code: failed (422) is een zakelijke afwijzing en bevat een stabiele error_key zoals INSUFFICIENT_CREDITS of NOT_FOUND; server_error (5xx) en netwerkfouten worden opnieuw geprobeerd met dezelfde idempotency key; rate_limited (429) wacht je af. Vertak nooit op de fouttekst.
Verstuurt Logistivo webhooks? Voor welke events?
Ja. Je registreert een https-adres en kiest de events die je belangrijk vindt; er komt een ondertekende POST binnen wanneer ze gebeuren. Vandaag kun je je op 13 events abonneren: lading aangemaakt/status gewijzigd/chauffeur toegewezen, aanvraag aangemaakt en status gewijzigd, bod uitgebracht/herzien/geaccepteerd, factuur concept/uitgegeven/geannuleerd, en magazijnreservering aangemaakt/status gewijzigd. Elke naam wordt gedekt door een eventklasse die daadwerkelijk wordt verzonden — niets wordt aangekondigd en daarna nooit afgevuurd, want zo'n event is een stille fout waar de integrator eeuwig op wacht. Abonnementen worden aangemaakt onder Settings › Integration › Webhooks, of vanuit een terminal met lg webhooks create.
Hoe verifieer ik de handtekening van een Logistivo-webhook?
Elk verzoek bevat een header X-Logistivo-Signature: t=,v1=. De ondertekende string is ".", het algoritme is HMAC-SHA256 en de sleutel is het secret van het abonnement. Vier regels: (1) verifieer de RUWE bytes — de body decoderen en opnieuw serialiseren (JSON.stringify / json_encode) maakt van dezelfde data andere bytes en dan klopt de handtekening niet meer; dit is verreweg de meest gemaakte fout; (2) controleer de tijdstempel en laat alles vallen waarbij |now − t| > 300 s, ook als de handtekening klopt; (3) vergelijk in constante tijd met hash_equals / timingSafeEqual; (4) ontdubbel op event_id, niet op de aflever-id — event_id blijft behouden bij een replay, terwijl de aflever-id verandert. Werkende ontvangers voor Node en PHP staan in examples/webhook-receiver/ in de repository en testen zichzelf met --selftest.
Wat gebeurt er als een webhook niet kan worden afgeleverd? Verlies ik het event?
Nee. Als je ontvanger geen 2xx teruggeeft, komt de aflevering in het retryschema: 60 · 300 · 1800 · 7200 · 21600 seconden, 6 pogingen in totaal, een venster van ongeveer 8,6 uur. ELKE fout behalve 410 Gone wordt opnieuw geprobeerd, 4xx inbegrepen — een zakelijk event verliezen kost meer dan een paar extra verzoeken. Na 10 opeenvolgende uitgeputte afleveringen wordt het abonnement stilgelegd en wordt de reden vastgelegd, zodat "waarom komt er niets binnen" beantwoordbaar blijft. Het afleveringslogboek bewaart elke poging (statuscode, duur, fout) en je kunt één aflevering opnieuw versturen vanuit het paneel of met lg webhooks replay. Incrementele sync (updated_since + cursor) is er nog steeds als vangnet.
Kan mijn AI-agent alles doen wat een gebruiker in het paneel kan doen?
Bijna alles. Elke schrijfactie in het paneel heeft een commando — gemeten tegen de schrijf-endpoints van het paneel is 100% van de endpoints binnen de scope gedekt — en dezelfde commando's staan open voor lg, voor HTTP en voor het MCP-kanaal. De bewuste uitzonderingen zijn stappen rond identiteit en geld: inloggen, een pakket kopen, een kaart toevoegen met 3D Secure, juridische teksten goedkeuren en een account sluiten blijven in de browser van de persoon, en lg handoff-links generate geeft daarvoor de link terug. Integratiesleutels, webhooks en de sandbox worden beheerd met ingebouwde lg-commando's, omdat ze geheimen één keer teruggeven.
Kan ik bestanden zoals pdf's of foto's vanuit de CLI of de API aan commando's doorgeven?
Ja. Zet bij lg een @ voor een lokaal pad (--attachment_uuid=@./cmr.pdf) en lg uploadt het bestand eerst; --file is een snelkoppeling wanneer een commando één bestandsveld heeft, en lg upload uploadt alleen. Via HTTP stuur je het bestand als multipart naar POST /api/common/commands:upload en geef je de teruggegeven attachment_uuid door aan het commando; MCP-clients gebruiken de tool upload_attachment. Het type wordt uit de inhoud bepaald, uploads horen bij de gebruiker en blijven 24 uur bruikbaar, en hetzelfde bestand opnieuw uploaden geeft dezelfde id terug.
Wat is het verschil tussen een integratiesleutel op employee- en op managerniveau?
Het toegangsniveau bepaalt hoe zwaar het werk mag zijn dat een sleutel doet. Een employee-sleutel, de standaard voor nieuwe sleutels, voert dagelijkse operaties uit: ladingen, aanvragen, biedingen, ritten, wagenpark, documenten en contacten. Een managersleutel mag ook beheerwerk doen — teamleden en rollen, bedrijfsinstellingen, integratiesleutels, bankrekeningen, opgeslagen kaarten, affiliate-uitbetalingen. Een sleutel heeft nooit meer rechten dan de persoon namens wie hij handelt, en een employee-sleutel die een managercommando aanroept, krijgt INSUFFICIENT_KEY_LEVEL. Wijzig het niveau in het paneel of met lg keys update --access-level=manager.
Kan een affiliate (doorverwijspartner) de CLI gebruiken?
Ja. Een affiliate-account krijgt een eigen catalogus — 55 commando's voor doorverwijzingen, leads, CRM-notities en -taken, salespresentaties, verdiensten en uitbetalingen — en gebruikt die vanuit lg, HTTP of MCP, net als elke andere rol. Een uitbetaling aanvragen of annuleren en de bankrekening voor uitbetalingen wijzigen vereisen een sleutel op managerniveau en een bevestiging. Een bedrijf dat ook verlader, vervoerder of douane-expediteur is, ziet beide catalogi.
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.