Logistivo CLI: opere sua logística pelo terminal e pelo seu ERP

Um único catálogo de comandos alimenta três superfícies: o cliente de terminal lg, o assistente de IA dentro do painel e o canal ao qual assistentes de IA externos se conectam. Uma capacidade é escrita uma vez e aparece nas três — e toda ação de escrita do painel agora tem um comando, então seus scripts e seus próprios agentes de IA podem fazer o trabalho que sua equipe faz na tela. Pagamentos, consentimento legal e encerramento de conta ficam no navegador de propósito. Esta página é um contrato. A tabela de comandos abaixo não é escrita à mão; ela é gerada a partir do registro de comandos ao vivo a cada requisição.

O que é a Logistivo CLI?

A Logistivo CLI (lg) é um cliente de linha de comando que executa o trabalho da sua conta Logistivo — cargas e viagens, demandas, propostas e concorrências, frota e motoristas, documentos, contatos e contas correntes, faturas e contabilidade, armazém e estoque, membros da equipe e tarifas aduaneiras — a partir de um terminal, de um script ou do seu próprio agente de IA. Os comandos não vêm embutidos no cliente: o cliente baixa o catálogo de comandos do servidor e se monta a partir dele. Os mesmos comandos podem ser chamados via HTTP sem instalar nada — é o caminho que as integrações de ERP e CRM usam — e pelo canal MCP ao qual assistentes de IA externos se conectam.

• Um único formato de comando: lg --parameter=value. Hoje o catálogo tem 519 comandos em 125 domínios; a lista mais ampla que um único perfil vê tem 452 comandos em 112 domínios.
• Toda ação de escrita do painel tem um comando — medido contra os endpoints de escrita do painel, 100% dos que estão no escopo estão cobertos. Pagamentos (3D Secure), consentimento legal e encerramento de conta ficam no navegador de propósito; para esses, um comando devolve um link.
• Comandos que recebem um documento ou uma foto também funcionam fora do navegador: escreva --attachment_uuid=@./cmr.pdf e o lg faz o upload do arquivo primeiro; via HTTP, você faz o upload para /api/common/commands:upload e passa o attachment_uuid retornado.
• As chaves de integração têm um nível de acesso: employee (o padrão para chaves novas) para as operações do dia a dia, manager para equipe, configurações, chaves e dinheiro. Uma chave nunca tem mais direitos do que a pessoa em nome de quem ela age.
• Flags nunca são inventadas: toda flag é um nome de parâmetro do próprio JSON Schema do comando, assim como o seu tipo e se ela é obrigatória.
• Comandos de escrita pedem confirmação; os irreversíveis nunca rodam sem ela (HTTP 409, código de saída 4 da CLI).
• Repetir não cria duplicatas: uma chamada que carrega um idempotency_key roda no máximo uma vez.
• Toda execução cai em uma única trilha de auditoria — fica registrado se ela veio de um terminal, do chat ou de um assistente.

O que está no ar hoje e o que está a caminho

Esta seção fica no topo da página de propósito. O erro mais caro que um documento de integração pode cometer é descrever um endpoint que ainda não está aberto como se estivesse: o integrador escreve o código, o endpoint retorna 404 e a confiança não volta.

Como o contrato está congelado, o código de integração que você escreve hoje continua funcionando à medida que as peças restantes são abertas. Campos que você não conhece devem ser ignorados; é essa regra que nos permite adicionar sem quebrar.

• Catálogo de comandos e tabela de identidade — A identidade pública domínio/verbo de cada comando está congelada, e a versão do contrato é publicada como 1 em toda resposta do catálogo e no header X-Contract-Version. A tabela desta página é gerada a partir do registro ao vivo: um comando adicionado no servidor aparece aqui sozinho, e um comando removido desaparece.
• Endpoint de descoberta sem autenticação — GET /api/public/cli/catalog — nomes de comandos, identidade domínio/verbo, descrição, parâmetros em JSON Schema, flags de barreira e os campos de versionamento (since, deprecated_at, replaced_by, aliases). Sem autenticação: emitir um token é um passo que vem DEPOIS da decisão de integrar, não antes. A resposta não carrega absolutamente nenhum dado de tenant.
• Endpoints autenticados de catálogo e de execução — GET /api/common/commands, GET /api/common/commands/{name} e POST /api/common/commands/{name}. A barreira de perfil, a barreira de confirmação, a idempotência e a trilha de auditoria ficam em um único ponto de aplicação, pelo qual o chat e o terminal também passam.
• Cobertura do painel: toda ação de escrita tem um comando — 519 comandos em 125 domínios, verificados contra os endpoints de escrita do painel: todo endpoint dentro do escopo é coberto por um comando (um espelho do endpoint ou o mesmo serviço compartilhado), e nenhum fica sem comprovação. Deliberadamente fora do escopo: pagamentos com 3D Secure, consentimento legal, encerramento de conta e login, que ficam no navegador; gestão de chaves, webhooks e sandbox, que são comandos nativos do lg; e os endpoints próprios do aplicativo do motorista.
• Preflight (dry_run): veja sem executar — Com dry_run: true no corpo da requisição, o comando não roda: a validação, a barreira de perfil/escopo, a resolução do alvo e o cálculo de créditos são todos executados e uma prévia é devolvida; nada é gravado, nenhum crédito é gasto e a chave de idempotência não é consumida. O endpoint de lote também aceita isso, por lote. Um preflight nunca entra no handler do comando; quando o recurso foi lançado, 178 preflights em todos os comandos de escrita do catálogo naquele momento não produziram uma única instrução de escrita.
• Chaves de integração — Chaves de API que agem em nome de um membro real da equipe, emitidas no painel ou com lg keys create: escopo de leitura/escrita, um nível de acesso (employee por padrão, ou manager), validade, último uso, rotação, transferência e revogação. lg login --api-key, lg whoami e um lg logout que revoga no servidor são construídos sobre elas.
• Sandbox — ensaie escritas sem tocar a produção — Um tenant sandbox separado por empresa, com o mesmo catálogo de comandos; ele é aberto por autoatendimento e emite sua própria chave. Os créditos, o marketplace e o roteamento de webhooks são separados entre os dois ambientes; o ambiente é derivado da empresa da chave e não pode ser informado na requisição.
• Versionamento, taxonomia de erros, idempotência e limites de requisições — Os comandos carregam since / deprecated_at / replaced_by / aliases, e um comando descontinuado responde com um header X-Deprecated. Falhas de negócio carregam um error_key estável ao lado do error_code de nível de transporte, e o dicionário de chaves é publicado no catálogo. As chaves de idempotência são restritas à sua empresa, vinculadas a um único comando e bloqueadas por 24 horas. Os limites de requisições (rate limits) são por token, em três buckets, e todo 429 carrega Retry-After.
• Webhooks de saída: um POST quando algo acontece — O push assinado está no ar para 13 eventos. As inscrições são gerenciadas no painel ou com lg webhooks; a assinatura carrega seu próprio timestamp, o cronograma de novas tentativas é de 60 · 300 · 1800 · 7200 · 21600 segundos e o motivo do silenciamento é sempre registrado. Todo nome de evento é respaldado por uma classe de evento que é de fato disparada — nada é anunciado para depois nunca ser enviado. O trilho de pull (updated_since + cursor) não foi removido: o push foi adicionado ao lado dele, não no lugar dele.
• Comandos que recebem arquivos — 33 comandos recebem um documento ou uma foto — um CMR, uma fatura, um documento de registro do veículo, fotos de paletes. Faça o upload uma vez para POST /api/common/commands:upload, ou deixe o lg fazer isso com --attachment_uuid=@./file.pdf, e passe o attachment_uuid retornado; clientes MCP usam a ferramenta upload_attachment. O tipo de arquivo é detectado pelo conteúdo, e um upload continua utilizável por 24 horas.
• O cliente de terminal lg — Publicado no npm sob a licença MIT: instale com `npm install -g @lgstv/lg`, ou execute sem instalar via `npx @lgstv/lg`. É um único arquivo sem dependências e, como a superfície HTTP é aberta, você pode integrar sem ele. Ele faz login com um código de aprovação que você confirma no navegador e depois continua conectado, renovando a sessão sozinho; faz o upload de arquivos locais para você (@path, --file, lg upload), gerencia chaves de integração (lg keys), nunca recebe um segredo na linha de comando, respeita Retry-After, repete 5xx com a mesma chave de idempotência e avisa sobre comandos descontinuados e versões mais novas do contrato.
• Sincronização incremental: paginação por cursor e updated_since — O contrato abaixo (limit + cursor assinado e opaco, next_cursor, updated_since) é fixo e está sendo implantado nos comandos de listagem. Até que um determinado comando de listagem anuncie cursor e updated_since no seu JSON Schema, trate-o como uma janela pequena: teto de 20 linhas, sem cursor.

O que torna isso diferente: o cliente não conhece nenhum comando, ele os desenha

Esta é a única decisão que dá sentido ao resto da página. Em uma CLI comum, os comandos ficam dentro do cliente; na Logistivo, eles ficam no servidor.

No arranjo clássico, quando o servidor ganha uma capacidade, o cliente precisa de uma nova versão e o usuário precisa instalá-la. Nesse meio-tempo, os dois lados sabem coisas diferentes — e esse é o modo de falha mais silencioso das integrações: o script roda, o código de saída é 0 e o comando simplesmente não descreve o que o servidor consegue fazer.

Na Logistivo, a definição de um comando é um único registro: seu nome, o que ele faz, seus parâmetros em JSON Schema, quais perfis podem vê-lo, se ele precisa de confirmação e se o seu efeito é reversível. Quando o lg inicia, ele baixa esse catálogo e gera a partir dele o texto de ajuda, as flags e a validação de entrada. No momento em que um comando é adicionado no servidor, o lg passa a conhecê-lo — sem nenhuma atualização do cliente.

O mesmo catálogo alimenta o assistente de IA do painel e o canal ao qual assistentes de IA externos se conectam. Uma capacidade é escrita uma vez e aparece em três lugares — e os três passam pela mesma barreira de perfil, pela mesma barreira de confirmação e pela mesma trilha de auditoria. Não existe um inventário separado de comandos da CLI; se existisse, as três superfícies divergiriam silenciosamente em seis meses.

• Sem divergência de versões — A lista de comandos que o cliente conhece é, por construção, a lista que o servidor tem. “Qual versão do lg tem este comando?” é uma pergunta que não existe.
• Nomes de flags nunca são adivinhados — As flags de um comando são exatamente os nomes de parâmetros do seu JSON Schema. A forma de saber o que um comando aceita não é ler um documento, mas ler o catálogo — e o catálogo está sempre atualizado.
• Sua CLI é do tamanho da sua conta — O catálogo é filtrado por perfil: um comando que o seu perfil não pode ver nunca aparece na sua lista. Uma conta de transportadora vê 452 comandos, um embarcador 448, um despachante aduaneiro 312, e uma conta de afiliado (parceiro de indicação) vê um conjunto próprio, de 55 comandos.
• A documentação não tem como ficar defasada — A tabela de comandos desta página vem do mesmo registro. Não existe, em lugar nenhum, uma lista que uma pessoa precise manter sincronizada com a realidade.

A regra de nomenclatura — como os nomes de comandos crescem

O catálogo vai crescer. Novos comandos não são nomeados de improviso; seis regras são aplicadas. Nós as publicamos aqui porque esses são os nomes que a sua integração vai escrever durante anos, e a previsibilidade deles tem valor para você.

• Um domínio é uma entidade no plural — loads, demands, invoices, export-documents. Domínios de duas palavras ficam em kebab-case. A única exceção é um substantivo incontável: stock nunca vai para o plural, porque, em inglês, “stocks” significa outra coisa.
• Todos os verbos de uma entidade ficam em um único domínio — loads reúne todo verbo que atua sobre uma carga: create, list, get, update, set-status, assign-driver, list-problems, archive e outros. Abrir um novo domínio por verbo (load-statuses, load-drivers) obrigaria o usuário a procurar a mesma entidade em três lugares.
• O verbo nunca vaza para o domínio; o domínio é o que MUDA — Atribuir um motorista muda a carga, não o motorista, então o comando é lg loads assign-driver. O objeto indireto (-driver) é anexado ao verbo, nunca ao domínio.
• Um sub-recurso nunca ganha domínio próprio — Uma linha de fatura e um item de documento não podem ser listados sozinhos; eles são acessados pelo seu dono — lg invoices add-line, lg export-documents add-item. Um único teste decide: se você não consegue listar ou obter a coisa de forma independente, ela não é um domínio.
• Restringir é uma flag, não um novo verbo — lg fleet-documents list --days=30 está correto; não existe um verbo “list-expiring” separado, porque a janela já é um parâmetro. Um verbo qualificado só é usado quando as linhas que ele retorna não são a entidade do domínio: loads list-problems retorna sinalizações de problema, não cargas.
• O par (domínio, verbo) é único em todo o catálogo — Mesmo para dois comandos cujos perfis nunca se sobrepõem. Se o mesmo par fosse dado a dois comandos, o seu código de integração estaria olhando para um único nome enquanto a CLI executaria coisas diferentes dependendo de quem a chamou.

Cobertura: tudo o que há no painel, a partir de um comando

Muitas equipes conectam a Logistivo ao seu próprio agente de IA ou harness de automação, e um agente só é útil se consegue terminar o trabalho. Por isso, a regra é simples: tudo o que um usuário de escritório pode alterar no painel, um comando também pode — atrás da mesma barreira de perfil, da mesma barreira de confirmação e da mesma trilha de auditoria.

Isso é medido, não afirmado. Todo endpoint de escrita por trás do painel é verificado contra o registro de comandos, e um endpoint só conta como coberto quando um comando o declara como seu espelho HTTP ou chama o mesmo serviço compartilhado. Dos endpoints de escrita dentro do escopo, 100% estão cobertos e nenhum está sem comprovação. Todo endpoint deixado de fora tem um motivo escrito — etapas de identidade e de pagamento, o plano de controle da integração, os endpoints próprios do aplicativo do motorista, telemetria do cliente, cópias mortas sem nenhum chamador — e os que importam para um integrador estão listados abaixo.

Comandos que recebem um arquivo seguem a mesma regra: 33 comandos da tabela recebem um documento ou uma foto, e todos funcionam pelo lg, via HTTP e via MCP (veja Comandos que recebem arquivos).

O trabalho de gestão também é coberto, atrás de uma chave mais forte: 62 comandos da tabela — membros da equipe e perfis, configurações da empresa, contas bancárias, cartões salvos, chaves de integração — precisam de uma chave de integração de nível manager. Uma chave de nível employee, o padrão, executa as operações do dia a dia e é recusada nesses comandos com INSUFFICIENT_KEY_LEVEL.

Contas de afiliado (parceiro de indicação) têm um catálogo próprio: 55 comandos em 20 domínios — indicações, leads, notas e tarefas de CRM, apresentações de vendas, ganhos e repasses, além dos comandos de conta e de equipe que todo perfil tem. Os comandos exclusivos de afiliados não estão na tabela pública abaixo, que lista os três perfis do painel; uma conta de afiliado os vê em GET /api/common/commands e em lg commands. Uma empresa que é ao mesmo tempo afiliada e embarcadora, transportadora ou despachante aduaneira vê os dois conjuntos.

Um agente deve começar com lg users get (nome de API get_current_user): ele retorna o perfil, o nível de acesso da chave em uso, as permissões efetivas e se uma aprovação legal pendente ou um número de telefone não verificado está bloqueando as escritas neste momento — assim, o agente pode prever uma recusa em vez de colecioná-la.

A cobertura é medida por um relatório que compara o registro de comandos com os endpoints de escrita do painel; um endpoint do painel adicionado sem comando aparece nele como sem comprovação. Se você encontrar uma ação do painel que não consegue alcançar por um comando, informe o suporte.

• 1. Peça o link — O trabalho que precisa acontecer na própria sessão de navegador da pessoa não é um comando, mas a superfície de comandos sabe dele. lg handoff-links generate (nome de API get_browser_handoff_link) retorna um link de logistivo.com para as finalidades que o seu perfil permite: package_purchase, payment_cards, legal_documents, integration_keys, affiliate_demo_accounts e account_close. Ele é gratuito, não grava nada, e o link não carrega nenhum segredo — a pessoa faz login normalmente.
• 2. Entregue-o à pessoa — Mostre o link ao usuário ou envie-o pelo seu próprio canal. Ele conclui a etapa lá: a aprovação do contrato e o pagamento com 3D Secure de um pacote, a adição de um cartão, a aprovação de textos legais pendentes, a emissão de uma chave de API cujo segredo é exibido uma única vez, ou o encerramento da própria conta.
• 3. Leia o resultado com um comando — Depois que a etapa é concluída, o resultado volta a ficar visível para os comandos: o pacote e o saldo de créditos, o cartão salvo (mascarado, apenas os quatro últimos dígitos), a nova chave na lista de chaves. Um agente nunca recebe um número de cartão, um pagamento ou um consentimento em um chat.
• Pagamentos e 3D Secure — Comprar ou fazer upgrade de um pacote e adicionar um cartão exigem 3D Secure no navegador. Os comandos listam pacotes e preços, leem o saldo e o seu histórico, listam os cartões salvos (mascarados), definem o cartão padrão e removem um cartão; a compra em si passa pelo link de handoff.
• Consentimento legal — Aprovar textos legais é algo feito pela pessoa, no navegador. lg users get informa que uma aprovação está pendente; nenhum comando pode concedê-la.
• Encerramento de conta, login e senha — Encerrar a própria conta, fazer login e alterar a senha são etapas de identidade e ficam no navegador. lg user-accounts preview mostra o que encerrar a conta significaria, sem fazê-lo.
• Chaves de integração, webhooks e o sandbox — Gerenciá-los devolve segredos que precisam ser exibidos uma única vez, no seu terminal, por isso eles são comandos nativos do lg (lg keys, lg webhooks, lg sandbox) sobre os seus próprios endpoints HTTP, e não comandos do catálogo. O catálogo traz apenas os dois comandos de chave sem segredos: integration-keys list e integration-keys revoke.
• O chat do assistente do painel — Chaves de integração não podem conduzir o chat do assistente de IA dentro do painel; iniciar ou continuar uma execução com uma chave responde 403. Um agente se conecta, em vez disso, pelos endpoints de comandos, pelo lg ou pelo canal MCP — ali, cada comando roda no nível de acesso da chave e as suas escritas são registradas como escritas de integração.
• O aplicativo do motorista — Contas de motorista não têm catálogo de comandos, e o aplicativo do motorista mantém os seus próprios endpoints. Usuários de escritório gerenciam motoristas, os documentos, as despesas e as viagens deles por meio de comandos.

Instalação e identidade

lg é um script Node de arquivo único e sem dependências (Node 18+), publicado no npm como @lgstv/lg. O pacote instala dois comandos idênticos, lg e logistivo — use logistivo se lg já for um alias na sua máquina. Como é um único arquivo, copiar lg.mjs para o servidor de ERP de um cliente também funciona. Você não precisa do cliente para construir uma integração de ERP/CRM — os mesmos comandos estão disponíveis via HTTP.

1. Instale — Node 18 ou mais recente é tudo de que você precisa; não há outras dependências. Instale globalmente ou execute sem instalar via npx.

2. Faça login com um código de aprovação — lg login mostra um código de aprovação curto e abre logistivo.com/connect no seu navegador; via SSH, em CI ou com --no-browser, ele apenas imprime o endereço, que você pode abrir em qualquer dispositivo, inclusive no seu celular. Entre ali como de costume, confira se o código na página é o mesmo do seu terminal, escolha o acesso somente leitura ou de leitura e ação e aprove. Nada secreto é digitado no terminal: nem senha, nem chave, nem código de uso único. A sessão então continua conectada naquele computador — fechar o terminal não desconecta você, e o lg renova o access token sozinho antes que ele expire. lg logout também encerra a sessão no servidor, e você pode removê-la no painel em Settings › Integration keys › AI and CLI connections. lg login --password (e-mail e senha) continua disponível como alternativa. Requer lg 0.11 ou posterior.

3. Para servidores e CI: uma chave, não um código de aprovação — Um servidor ou um job de CI não tem ninguém para aprovar um código no navegador. Emita uma chave no painel (Settings › Integration keys) ou com lg keys create — opcionalmente em nome de um membro da equipe dedicado e com escopo restrito — e coloque-a em LOGISTIVO_TOKEN, ou salve-a com lg login --api-key. Enquanto a variável estiver definida, o arquivo de configuração nunca é lido. Detalhes: a seção “Conectando com uma chave de API”.

4. Verifique e explore o catálogo — lg commands lista todos os comandos que o seu perfil pode ver, agrupados por domínio; lg help imprime os verbos desse domínio, e lg help imprime a lista completa de parâmetros de um comando, com os tipos e quais deles são obrigatórios. Nenhum desses textos fica dentro do cliente — tudo vem do catálogo. Lembre-se de que a lista depende do seu perfil: os verbos de um domínio não são os mesmos para uma transportadora e para um embarcador (loads set-status, por exemplo, está apenas no catálogo da transportadora). Se faltar um verbo, verifique o seu perfil antes de verificar a sua instalação.

Nunca coloque a chave em controle de versão, em um log de CI ou em uma janela de chat. Se você entrou com um código de aprovação ou com uma chave de integração, lg logout também encerra esse acesso no servidor; em uma sessão com senha (lg login --password), ele apaga apenas a cópia LOCAL e diz isso explicitamente. A trilha de auditoria armazena seus argumentos, mas mascara como *** qualquer campo cujo nome contenha token, password, IBAN, card ou OTP, além de todo parâmetro que um comando declara como secreto.

• LOGISTIVO_TOKEN — Token de acesso pessoal. Enquanto estiver definido, o arquivo de configuração nunca é lido — este é o caminho preferido em CI e em servidores.
• LOGISTIVO_BASE_URL — Raiz do servidor. O padrão é https://logistivo.com. Altere apenas se estiver apontando para o seu próprio ambiente; a flag --base-url faz o mesmo para um único comando.
• LOGISTIVO_HOME — Diretório do arquivo de configuração e do cache do catálogo. O padrão é ~/.logistivo. Separe-o se você trabalha com duas contas na mesma máquina.
• LOGISTIVO_PROFILE — Com qual profile executar. `lg profile use` é a escolha persistente; esta variável vale para uma única execução e é a forma mais curta de alternar entre um profile de produção e um profile de sandbox em CI. Um nome de profile desconhecido não é ignorado silenciosamente — ele gera um erro.
• NO_COLOR — Quando definida, nenhuma cor ANSI é impressa (a forma permanente da flag `--no-color`). Ative-a em uma ponte que grava em um arquivo de log ou na saída de CI; as sequências de escape de cor quebram as ferramentas que leem esses logs depois.

Ergonomia do cliente

Estes recursos facilitam o uso diário do cliente `lg`. Nenhum deles altera o contrato HTTP — pule esta seção se você integra diretamente via HTTP.

• Vários ambientes e chaves — Mantenha staging e produção, ou as suas pontes de embarcador e de transportadora, em profiles separados. A lista de profiles nunca imprime um token; cada linha mostra a impressão digital sha256 do token. O catálogo de comandos fica em cache por profile, host e token, então dois perfis nunca conseguem ver a lista de comandos um do outro.
• Sincronização incremental: lg sync — Executa em um único comando o loop de sincronização descrito no cookbook: uma marca d'água (watermark) por entidade, updated_since com cursor, saída JSONL e uma margem de segurança de cinco minutos. Use --full para o primeiro backfill. O comando é somente leitura; não existe flag --write. lg sync --list deriva do catálogo as entidades sincronizáveis para o seu perfil.
• Experiência de erro e autocompletar no shell — Em um 422, o cliente nomeia o campo rejeitado como a flag que você digitou, junto com o error_key estável e a explicação que o próprio catálogo dá para ele. Em um 409, ele imprime a linha de comando pronta com --yes; em um 429, ele espera o tempo de Retry-After. O autocompletar do shell cobre domínios, verbos, flags e valores de enum, e funciona offline.
• Parâmetros secretos nunca vão para a linha de comando — Alguns comandos recebem um segredo — conectar a integração contábil Paraşüt, por exemplo, exige as credenciais de cliente e a senha desse sistema. O lg nunca aceita um valor assim como flag, porque ele acabaria no histórico do seu shell e na saída do ps: ele o pede sem eco, ou o lê de ---file=PATH ou de stdin (---file=-), e o mantém apenas na memória. Um comando cujo parâmetro obrigatório é secreto só roda a partir do lg: chamado do chat, via MCP ou dentro de lg batch, ele é recusado com SECRET_REQUIRES_CLI. A trilha de auditoria sempre registra o valor como ***.

Conectando com uma chave de API

Um ERP, CRM, script ou agente de IA se conecta à Logistivo com uma chave de integração emitida no painel ou com lg keys create. A chave age em nome de um membro real da equipe: o perfil dessa pessoa decide a lista de comandos, o nível de acesso da chave decide o quão pesado pode ser o trabalho e, quando essa pessoa sai da equipe, a chave morre junto. Não existe uma “conta de serviço” sintética, e não vai existir — o isolamento multi-tenant está vinculado ao usuário, e uma ponte sem dono é do tipo que continua gravando em silêncio durante anos.

1. Emita uma chave no painel — Settings › Integration keys › New key. Dê um nome a ela (“ERP nightly sync”), escolha o escopo e o nível de acesso e, se quiser, encurte a validade. A chave é exibida uma única vez, apenas naquela tela; o servidor não a armazena. Se você a perder, Rotate emite uma nova — a antiga se torna inválida imediatamente.

2. Conecte-se a partir do terminal — lg login --api-key valida a chave, imprime a identidade e o escopo e baixa o catálogo de comandos. lg whoami pergunta ao servidor com qual usuário, empresa, perfil e escopo você está executando. lg logout também revoga a chave no servidor, assim como encerra ali uma sessão aberta com código de aprovação (só o lg logout de uma sessão com senha não pode fazer isso).

3. Ou HTTP puro — A chave é um access token enviado no header Authorization: Bearer e funciona diretamente nos três endpoints de comandos. Em um servidor ou em CI, coloque-a em LOGISTIVO_TOKEN; enquanto essa variável estiver definida, o arquivo de configuração nunca é lido.

4. Ou gerencie as chaves a partir do terminal: lg keys — lg keys é o gêmeo de terminal da tela do painel: mesmos endpoints, mesma barreira (a permissão de gestão da equipe e, quando você o chama com uma chave, uma chave de nível manager). create, rotate e transfer devolvem um novo token uma única vez: com --save-profile=NAME, ele vai direto para um profile local e nunca é impresso; caso contrário, o lg o imprime uma vez. No modo --json, o token só é incluído se você adicionar --show-secret, e uma chamada --json sem nenhuma das duas flags é recusada antes de a requisição ser enviada, para que o token não possa cair silenciosamente na saída de um script. rotate, transfer e revoke pedem confirmação (--yes); uma chave é identificada pelo seu nome exato ou pelo seu uuid, nunca por um palpite. O nível de acesso é mantido sem alterações em uma chave rotacionada ou transferida.

O escopo é aplicado em toda a superfície da API, não apenas no catálogo de comandos: uma chave somente leitura passa nas requisições de leitura (GET/HEAD/OPTIONS), e todas as outras requisições de escrita respondem 403 forbidden. Há duas exceções deliberadas, e ambas são protegidas por uma barreira mais fina: o endpoint de execução de comandos (a decisão vem da própria flag read_only do comando, porque comandos que não gravam também são chamados com POST) e uma chave revogando a si mesma (lg logout, permitido também em uma chave somente leitura). Escopo, concessões por domínio e nível de acesso são três eixos independentes, e todos precisam passar: uma chave read não pode gravar nem no nível manager, uma chave write de nível employee não pode gerenciar a equipe, e uma concessão de domínio loads:write não abre o trabalho de gestão. Emita a chave em nome do membro com menos privilégios que cubra as suas necessidades: é o perfil que decide quais registros você consegue ver, para começo de conversa.

• read — O catálogo de comandos e os comandos que não gravam (list, search, preview). Um comando de escrita retorna 403 forbidden — antes da barreira de confirmação; uma chave somente leitura nunca chega nem a ver um 409. A escolha certa para sincronização noturna e relatórios.
• write — Todos os comandos. Comandos que exigem confirmação continuam pedindo-a com 409; confirm: true (--yes na CLI) funciona exatamente como antes. O escopo nunca afrouxa a barreira de confirmação.
• employee — O padrão para toda chave nova. Operações do dia a dia: cargas, demandas, propostas, viagens, frota e documentos de frota, documentos, contatos — todo comando que não precisa de permissão de gestão, além das permissões de frota. Um comando que precisa de mais responde 422 com error_key INSUFFICIENT_KEY_LEVEL e required_key_level: manager; o endpoint REST correspondente responde 403 com a mesma chave de erro. O nível certo para uma sincronização noturna de ERP, uma ponte de telemática ou um script de operações.
• manager — Tudo o que a pessoa em nome de quem a chave age pode fazer, inclusive gestão: membros da equipe e perfis, configurações da empresa, chaves de integração, contas bancárias e a verificação delas, cartões salvos, relacionamentos entre empresas, repasses de afiliados. Uma chave manager nunca acrescenta um direito que a pessoa não tem — sem a permissão de gestão da equipe, ela continua sem poder gerenciar a equipe. As chaves que existiam antes da introdução dos níveis de acesso são chaves manager, então elas se comportam exatamente como antes.
• Uma chave por integração — Se o CRM e o ERP compartilham uma chave, cortar um significa cortar o outro. Dê a cada ponte a sua própria chave; a lista as mostra pelo nome, de qualquer forma.
• Rotacionar — Emite um novo token e revoga o antigo imediatamente; a validade restante é mantida. Use em caso de suspeita de vazamento e em intervalos regulares. A integração recebe 401 até ser atualizada com o novo token.
• Revogar — A chave é encerrada de forma permanente; isso não pode ser desfeito, emita uma nova chave se necessário. Se o membro em nome de quem a chave age for removido da equipe ou desativado, a chave cai sozinha.
• Validade e limite — A validade padrão é de 180 dias; você pode encurtá-la na criação, nunca estendê-la. Um usuário pode ter no máximo 10 chaves ativas. O horário do último uso fica visível na lista; uma chave nunca usada diz isso explicitamente.
• Quem gerencia — Emitir, rotacionar, transferir e revogar está aberto a gestores com permissão de gestão da equipe — a mesma barreira de adicionar ou remover membros da equipe — e, quando feito com uma chave de integração, essa chave precisa ser de nível manager. Um gestor pode emitir uma chave em nome de outro membro; para uma ponte, recomenda-se um membro dedicado e com escopo restrito.

Os primeiros dez minutos: do painel à sua primeira chamada

Os minutos mais caros de uma integração são os dez primeiros. Os quatro passos abaixo apresentam esse caminho em ordem; a mesma ordem existe no painel como um assistente de configuração (Settings › Integration › Setup wizard), e o assistente de configuração chama exatamente os endpoints descritos aqui. Um desenvolvedor sem acesso ao assistente de configuração chega ao mesmo lugar lendo esta seção.

Nenhum dos quatro passos termina com “eu enviei”. Se a chave realmente funciona, quem responde é o registro de requisições; se o webhook realmente chega, quem responde é o registro de entregas. Ambos estão abertos no painel e no lg. Uma configuração que nunca é medida é uma configuração que apenas se acredita que funciona.

• 1. Decida o que você vai fazer — defina o escopo primeiro — Não dá para decidir depois o que uma chave pode ver: você escolhe o escopo ao emiti-la. Há dois eixos. O escopo grosso (read / write) responde apenas “ela pode gravar?”. O escopo fino (concessões por domínio: loads:read, invoices:write) diz quais domínios ela pode tocar e, no momento em que é definido, a chave passa a ser fail-closed — todo domínio que você não selecionou, e todo endpoint que não corresponde a nenhum domínio, retorna 403. A lista de domínios no painel não é uma lista escrita à mão; ela é derivada do catálogo de comandos ao vivo do seu perfil e mostra quantos comandos e endpoints REST cada domínio abre. Os endpoints do catálogo de comandos, de “quem sou eu” (current) e de “sair” são sempre isentos de escopo: uma chave sempre precisa conseguir descrever e encerrar a si mesma. O terceiro eixo é o nível de acesso: employee (o padrão) executa as operações do dia a dia, manager também faz trabalho de equipe, configurações, chaves e dinheiro. Escolha employee, a menos que a ponte faça trabalho de gestão.
• 2. Emita a chave — o token é exibido uma única vez — Settings › Integration › New key. Dê um nome a ela (“ERP nightly sync”), escolha o usuário em nome de quem ela roda e o nível de acesso e, se quiser, encurte a validade. O token bruto é devolvido apenas nessa resposta; o servidor não o armazena e não existe “mostrar de novo” no painel. Se você o perder, rotacione para obter um novo, e o antigo morre na hora. Nunca coloque o token em controle de versão, em um log de CI ou em uma janela de chat; coloque-o no cofre de segredos do sistema de destino.
• 3. Faça a primeira chamada — e veja que ela REALMENTE chegou — Duas requisições bastam. A primeira comprova a sua identidade (ela é isenta de escopo e funciona com qualquer chave): o escopo é o que você esperava, o status está ativo, o expires_at está se aproximando? A segunda lê dados reais do domínio que você escolheu. Se ela passar, a identidade, o escopo, a barreira de e-mail e o caminho de rede estão todos corretos. Se não passar, não tente adivinhar: o próprio registro de requisições da chave mostra, linha por linha, qual endpoint foi rejeitado, com qual código e com qual chave de erro estável (INSUFFICIENT_SCOPE, IP_NOT_ALLOWED, KEY_ACTOR_BLOCKED …). No painel, esse registro é a janela “Recent requests”; no terminal, é lg logs. O assistente de configuração observa exatamente esse registro e se recusa a deixar a etapa verde até ver uma chamada real bem-sucedida.
• 4. Configure o webhook — e verifique a assinatura antes de qualquer coisa — Esperar por eventos é mais barato do que perguntar a cada minuto. Registre um endereço https, escolha os eventos que lhe interessam e vincule a inscrição à sua chave: se a chave for revogada, a entrega também para. O segredo é exibido uma única vez, na criação. O seu endpoint receptor precisa verificar a assinatura primeiro: a string assinada é "{t}.{raw body}" e o algoritmo é HMAC-SHA256; o timestamp fica DENTRO da assinatura, então descarte qualquer requisição com mais de 300 segundos, mesmo quando a assinatura é válida. Compare em tempo constante e nunca serialize o corpo de novo — no momento em que você interpreta o JSON e o imprime novamente, a assinatura deixa de bater. No painel, “Send test” dispara um ping real e assinado, e você pode acompanhar a entrega tentativa por tentativa.

Sandbox: pratique escritas sem tocar a produção

O preflight (dry_run) diz o que um comando FARIA; mas se a idempotência realmente repete o resultado, se o webhook realmente é entregue, como são os ramos de erro e de onde vem o crédito só se vê em uma escrita REAL. É para isso que serve o sandbox: um tenant separado que espelha a sua empresa — mesmo código, mesmo catálogo de comandos — e nunca toca o seu livro-razão de produção.

O sandbox não é uma flag de requisição, é um TENANT. Uma empresa Logistivo separada, aberta para a sua: seu próprio usuário, seu próprio pacote, seu próprio registro de créditos, suas próprias inscrições de webhook. O ambiente é DERIVADO da empresa da chave e não pode ser informado por quem chama, então, mesmo que você escolha o profile errado, a requisição para no servidor com 403 ENVIRONMENT_MISMATCH. “Achei que estava gravando no sandbox e gravei na produção” é estruturalmente impossível.

A superfície é idêntica — e isso foi medido: o catálogo que uma chave de sandbox monta é o mesmo que a sua chave de produção monta (em uma chave de embarcador, 448 comandos dos dois lados). Uma ponte que funciona no sandbox funciona na produção; nada do que você aprende precisa ser aprendido duas vezes.

O sandbox não abre vazio: ele contém dados iniciais gerados (NÃO copiados) — contatos, cargas nas duas direções e demandas. Os nomes são abertamente inventados e os endereços de e-mail ficam no domínio @sandbox.invalid; nenhuma linha de um tenant real é jamais lida, clonada ou usada como modelo.

De propósito, NÃO existe botão de reset, e nenhum registro, arquivo ou documento é jamais apagado. Se você quiser recomeçar do zero, a renovação abre uma nova geração e a antiga permanece, aposentada. Algumas centenas de linhas de ensaio acumuladas não custam nada perto de uma rotina de exclusão ligada ao tenant errado.

• 1. Abra o sandbox — Um sandbox por empresa. O endpoint exige a permissão de gestão da equipe (team.manage), então um administrador da sua empresa faz isso. Se ele já existir, o mesmo endpoint responde via GET com o seu estado: id da empresa, crédito restante, número de chaves ativas, inscrições, histórico de gerações e os tetos.
• 2. Emita uma chave de sandbox e guarde-a como um segundo profile — A chave é emitida em nome do próprio usuário-ponte do sandbox e volta carimbada com environment: sandbox; o token bruto aparece apenas nessa resposta. Do lado do lg, não substitua a sua chave de produção — mantenha AS DUAS como profiles separados; --sandbox e --live são seletores para uma única execução.
• 3. Grave de verdade — Nada de --dry-run aqui; gravar é justamente o objetivo. Envie a mesma chave de idempotência duas vezes e veja a segunda resposta voltar como status: replayed — esse é o resultado medido no sandbox. Chame de propósito um comando com barreira sem confirmação e leia o corpo do 409; tente um comando fora do seu escopo e leia a recusa. Nada disso deixa rastro no seu livro-razão de produção: o seu saldo de produção fica inalterado durante essa mesma execução.
• 4. Leia o checklist antes de ir para produção — O endpoint de go-live responde com base no que você REALMENTE fez no sandbox: você gravou, viu os ramos de erro, um webhook foi entregue, você tirou o receptor do endereço de ensaio, colocou uma data de expiração na chave? Cada item volta como pass / todo / unknown. A mesma resposta também traz uma PROPOSTA DE ESCOPO derivada dos comandos que você realmente chamou — use-a para emitir a sua chave de produção sem que ela seja mais ampla do que o necessário.
• Créditos e faturamento — O sandbox tem o seu próprio registro de créditos, e o seu saldo de produção não se move. Isso é uma estrutura, não uma verificação: o crédito é contado por empresa, e o sandbox é uma empresa separada. Ele abre no plano gratuito, não tem forma de pagamento e fica fora da janela de cobrança mensal — não consegue chegar a uma fatura por nenhum caminho.
• Marketplace — Uma demanda que você abre no sandbox NÃO aparece nas telas de transportadoras reais e NÃO chega à caixa de entrada de e-mail ou de push delas; e você também não vê demandas reais. A separação é simétrica e aplicada em duas consultas separadas: para quem uma demanda é VISÍVEL e para quem ela é ENVIADA são perguntas diferentes.
• Webhooks — As inscrições também carregam o carimbo de ambiente. Um evento do sandbox nunca é entregue a uma inscrição de produção, e um evento de produção nunca chega a uma do sandbox; para uma inscrição cujo carimbo divergiu, nenhuma entrega sequer é aberta. Como o teto de inscrições é por empresa, as suas inscrições de ensaio não consomem a sua cota de produção.
• Dados iniciais — Os registros de exemplo dentro do sandbox são GERADOS, nunca copiados de tenants reais. A geração é idempotente: uma segunda chamada não coloca uma segunda camada de dados por cima dos seus próprios registros.
• O mesmo catálogo — O seu perfil é o seu perfil também no sandbox, e a lista de comandos é idêntica — medido: 448 comandos dos dois lados. O sandbox não é uma demo reduzida; é um gêmeo da sua empresa.
• Limite atual: inscrições de webhook não podem ser gerenciadas com uma chave de sandbox — Os endpoints de inscrição exigem a permissão de gestão da equipe (team.manage), e o usuário-ponte do sandbox não tem nenhum perfil de equipe, então `lg --sandbox webhooks …` responde 403 hoje. Toda a superfície de comandos funciona — a restrição está apenas no registro de inscrições. Se você quiser ensaiar webhooks no sandbox, fale com o suporte; isso foi medido e está registrado como uma lacuna em aberto.
• GET /api/common/integration-sandbox — Estado: se existe, qual empresa, crédito restante, número de chaves e de inscrições ativas, histórico de gerações, os tetos e um guia de gatilhos mostrando qual comando dispara qual evento.
• POST /api/common/integration-sandbox — Abre o sandbox (um por empresa, idempotente). Exige a permissão team.manage.
• POST /api/common/integration-sandbox/keys — 201 + a chave e o token bruto (só aqui, só uma vez). O carimbo environment: sandbox é derivado da empresa; quem chama não pode informá-lo.
• GET /api/common/integration-sandbox/go-live — O checklist de go-live e uma proposta de escopo — calculados a partir do seu tráfego real no sandbox.
• POST /api/common/integration-sandbox/renew — Abre uma nova GERAÇÃO do sandbox e aposenta a anterior.

O modelo de comandos

Existe uma única gramática, e ela não tem exceções. Para saber como chamar um comando, a única coisa de que você precisa é o que o catálogo diz sobre ele.

lg loads list --status=in_transport --limit=20 --json

Os nomes das flags são os nomes dos parâmetros do schema, e o lg aceita as duas grafias: --load_code e --load-code chegam ao mesmo campo (lg help imprime a forma kebab-case). Ver uma flag, portanto, já diz em qual campo JSON ela vai parar, e passar da CLI para HTTP não exige tradução de nomes. Um parâmetro booleano escrito sem valor é true (--only_open); o oposto é --no-only_open. Escreva um argumento cujo valor começa com hífen como --flag=value; caso contrário, uma flag esquecida engole silenciosamente a seguinte como seu valor. Em um comando que recebe arquivo, coloque @ na frente de um caminho local (--attachment_uuid=@./cmr.pdf) — veja Comandos que recebem arquivos.

• lg — O cliente.
• loads — O domínio — a entidade com a qual você está trabalhando, no plural.
• list — O verbo — o que você faz com essa entidade, tirado de um vocabulário fechado que só cresce por decisão deliberada: verbos simples (list, get, create, update, delete, search, preview, generate, extract …) e verbos compostos que nomeiam o que é anexado ou alterado (add-document, set-status, assign-driver). lg help lista os verbos de um domínio.
• --status=in_transport — Um parâmetro — seu nome é exatamente o nome do parâmetro no JSON Schema, e seu valor precisa corresponder ao tipo do schema. Um valor inválido em um campo enum nunca chega ao servidor.
• --limit=20 — Número de linhas em comandos de listagem. O teto é informado na descrição dos parâmetros de cada comando — tipicamente 20 em uma chamada de listagem simples e até 100 no modo de sincronização (com cursor ou updated_since).
• --json — Saída JSON bruta.
• --json — Imprime JSON bruto. Este é o único formato correto para scripts: a tabela alinhada padrão é para humanos, escolhe suas colunas a partir dos dados e pode mudar de layout sem aviso. Nunca escreva um script que faça parsing da saída em tabela.
• --yes, -y — Passa pela barreira de confirmação (confirm: true via HTTP). Use-a apenas em um script que sabe o que está prestes a fazer; em um comando irreversível, esta flag é um atalho para “não há como desfazer”.
• --idempotency-key= — Torna segura a repetição de um comando de escrita. Uma segunda chamada com a mesma chave não executa o comando de novo; ela devolve o primeiro resultado. Se você montar um loop de novas tentativas, gere a chave VOCÊ MESMO e envie a mesma em todas as tentativas.
• --dry-run — Executa um preflight em vez do comando: a validação, as barreiras e o cálculo de créditos rodam, e nada é gravado (veja a seção de preflight). Válida em todos os comandos e no lg batch.
• --refresh — Força uma atualização do catálogo. O lg mantém o catálogo em cache por uma hora; se você sabe que um comando acabou de ser adicionado no servidor, use isto em vez de esperar.
• --help, -h — Imprime a descrição do comando no catálogo, todos os parâmetros, o tipo de cada um, seus valores de enum e se são obrigatórios. Não há arquivo de ajuda dentro do cliente.
• --profile=, --sandbox, --live — Com qual profile executar esta única chamada. --sandbox e --live escolhem o profile que guarda uma chave de sandbox ou uma chave de produção; o ambiente é derivado da chave no servidor, então uma incompatibilidade para com 403 ENVIRONMENT_MISMATCH em vez de gravar no lugar errado.
• --base-url, --timeout, --verbose, --no-color, --version — Respectivamente: apontar um único comando para outro servidor, um timeout em segundos, detalhes da requisição/resposta, desativar a cor ANSI e a versão do cliente.

Exemplos reais

Todos os comandos abaixo existem hoje no catálogo; nenhum nome ou parâmetro aqui é inventado. As saídas estão abreviadas. As saídas mostram o nível `data.result`; via HTTP, o mesmo objeto chega dentro do envelope `{success, data:{…}}` (veja a API HTTP de comandos).

• Cargas atualmente na estrada — lg loads list --status=in_transport --limit=20
• Uma carga completa, em JSON bruto — lg loads get --load_code=FSK2158 --json
• Sinalizações abertas de consistência de documentos — lg loads list-problems --only_open=true --limit=10
• Resolva o país — lg countries search --query=Germany --json
• Filtre com o id resolvido — lg loads list --receiving_country_id=57 --date_from=2026-09-01 --limit=20
• Encontre um código HS a partir do nome de um produto — lg tariffs search --query="aluminium profile"
• Avance uma carga (somente perfil de transportadora) — lg loads set-status --load_code=FSK2158 --status=transit --date=2026-08-21 --yes
• Rascunho — lg export-documents create --doc_type=proforma-invoice --currency_code=EUR --json
• Gere o documento (com barreira) — lg export-documents generate --document_id=8412 --yes

Sem o cliente: a API HTTP de comandos

O lg é uma conveniência, não a porta. O catálogo e a execução passam por três endpoints HTTP (arquivos têm um quarto, o endpoint de upload — veja Comandos que recebem arquivos); uma integração de ERP ou CRM se conecta diretamente aqui. A identidade é um token de acesso pessoal enviado em Authorization: Bearer. TODA resposta volta no mesmo envelope: `{ "success": bool, "data": { … }, "code": "…", "message": { … } }`. Todo o contrato fica dentro de `data` — `contract_version`, `command`, `status` e, como saída do comando, `result`; em caso de falha, `error_code`, `error_key` e `error`. Os exemplos de resposta desta página mostram o objeto `data`, e não o envelope, para economizar espaço; não se esqueça de desembrulhar `data` no seu próprio código. `lg --json` também imprime o envelope INTEIRO, e é por isso que os caminhos jq começam com `.data.result…`. A única exceção é `/api/public/status`: esse endpoint não tem envelope, para que watchdogs possam disparar alertas sem precisar interpretá-lo.

Pedir confirmação com 200 + ok:false é proibido e nunca vai acontecer. O motivo é simples: os clientes tratam 200 como sucesso, então um pedido de confirmação devolvido como 200 mataria o fluxo silenciosamente e ninguém perceberia. Confirmação é sempre 409.

• GET /api/common/commands — Todo o catálogo que o seu perfil pode ver: contract_version; por comando, name, domain, verb, description, JSON Schema, read_only, confirmation_needed, irreversible, credit_cost, since, deprecated_at, replaced_by, aliases e os campos de acesso key_level, permission, file_params, secret_parameters e cli_only; no nível superior, o dicionário error_keys, rate_limits, idempotency_ttl_hours, os perfis do seu catálogo, o contrato de anexos (upload) e o nível de acesso da chave com que você está chamando. Envia um ETag; If-None-Match responde 304. ?domain= também corresponde a um domínio antigo (alias). Monte o seu cliente a partir disso; não fixe uma lista de comandos no código.
• GET /api/common/commands/{name} — Um comando completo. name é o nome congelado do comando no catálogo (list_loads), não a identidade da CLI. Um comando descontinuado responde com um header X-Deprecated.
• POST /api/common/commands/{name} — Execução. Corpo: { args, confirm?, idempotency_key? }. O status HTTP da resposta é o próprio resultado — qualquer coisa diferente de 200 é informação, não ruído. Os erros carregam error_code (transporte) e, para recusas de negócio, error_key.

Comandos que recebem arquivos

33 comandos da tabela recebem um documento ou uma foto: anexar um CMR a uma carga, ler códigos HS de uma fatura, criar um veículo a partir do seu documento de registro, estimar um palete a partir de fotos, enviar um documento da empresa, conferir uma fatura com um packing list. No navegador, você solta o arquivo em um formulário; em todos os outros lugares, são dois passos — fazer o upload do arquivo e depois passar o id dele ao comando.

Um parâmetro recebe um arquivo quando o seu nome termina em attachment_uuid ou attachment_uuids — photos[].attachment_uuid dentro de uma lista, front_attachment_uuid em um cheque. Você não precisa memorizar isso: toda linha do catálogo carrega file_params com os caminhos exatos, o schema marca esses campos (format: uuid, x-logistivo-file: true), e a resposta do catálogo carrega um bloco attachments com o endereço de upload, os tipos aceitos, os limites de tamanho e o tempo de vida. lg help também os mostra.

Fazer upload é uma escrita, então uma chave com escopo de leitura não pode fazer upload; qualquer chave com escopo de escrita pode, em qualquer um dos níveis de acesso. Os uploads pertencem ao usuário, não à chave: duas chaves do mesmo usuário veem os mesmos uploads, e ninguém pode usar os de outra pessoa. Um id desconhecido, expirado ou que não é seu simplesmente não é encontrado, e o motivo não é revelado.

Os anexos do chat do painel e os uploads de comandos são espaços separados: um arquivo anexado no chat do assistente não pode ser passado a um comando pelo id, e um upload de comando nunca aparece em uma conversa do chat.

Um upload não é um comando e não tem efeito de negócio por si só: nada acontece com os seus dados até que um comando use o id. É também por isso que o upload nunca pede confirmação — quem carrega a barreira é o comando que consome o arquivo.

• 1. lg: coloque @ na frente de um caminho local — O lg faz primeiro o upload do arquivo e depois executa o comando com o id retornado; um valor sem @ é o id de um arquivo que você enviou antes. Listas aceitam caminhos separados por vírgula ou uma flag repetida, campos aninhados aceitam JSON, e --file é um atalho quando o comando tem exatamente um campo de arquivo de nível superior. O lg verifica cada arquivo localmente (existência, tamanho, tipo) antes de qualquer envio, e o lg batch faz o upload de cada arquivo distinto uma única vez antes de o lote rodar.
• 2. HTTP: faça o upload e depois passe o attachment_uuid — Envie o arquivo como multipart/form-data em um campo chamado file. Um upload novo responde 201; o mesmo arquivo enviado de novo pelo mesmo usuário responde 200 com o status replayed e o mesmo id, e nada é gravado. Como em toda esta página, o exemplo mostra o objeto data dentro do envelope.
• 3. MCP: a ferramenta upload_attachment — Um cliente MCP não consegue enviar multipart, então o canal oferece uma ferramenta extra que não está no catálogo: upload_attachment recebe um nome de arquivo e o conteúdo em base64 e retorna o mesmo attachment_uuid. Ela chama o mesmo serviço do upload via HTTP, sob as mesmas regras.
• O tipo vem do conteúdo — O nome do arquivo e o tipo declarado são ignorados; a extensão armazenada é a detectada. Aceitos para upload: jpg, jpeg, png, webp, heic, heif, pdf, xlsx, xls, csv, txt, doc, docx, xml, zip. Cada comando aplica depois a sua própria lista, mais restrita, antes de qualquer execução e responde UNSUPPORTED_FILE_TYPE com os tipos aceitos, ou FILE_TOO_LARGE.
• Tamanho — Imagens de até 10 MB, outros arquivos de até 15 MB.
• Tempo de vida — Um upload pode ser usado por 24 horas. Depois disso, ele deixa de ser resolvido (ATTACHMENT_NOT_FOUND) — mas não é apagado. Faça o upload de novo se um comando falhar por esse motivo.
• Mesmo arquivo, mesmo id — Enviar o mesmo arquivo de novo (mesmo nome, tamanho e conteúdo) retorna o id existente em vez de gravar um novo, desde que ainda lhe reste pelo menos uma hora, e isso não consome o seu teto diário.
• Tetos diários — 300 uploads por usuário por dia (TOO_MANY_FILES) e 2 GB por empresa por dia (DAILY_LIMIT_REACHED); ambos respondem 429 com retry_after.
• POST /api/common/commands:upload — Upload multipart no campo file. 201 para um upload novo, 200 com o status replayed para o mesmo arquivo. Retorna data.attachment: attachment_uuid, filename, mime_type, size_bytes, sha256, extraction_status, expires_at e reused.

A barreira de confirmação e os comandos irreversíveis

Todo comando do catálogo carrega duas flags: confirmation_needed (se exige aprovação explícita antes de rodar) e irreversible (se o seu efeito pode ser desfeito). São perguntas separadas, e ambas são aplicadas no servidor, em vez de ficarem a cargo da boa educação do cliente.

A barreira trata de responsabilidade, não de regras de negócio. Enviar uma proposta é o primeiro passo rumo a um contrato de frete; emitir uma fatura cria um lançamento contábil; uma movimentação de estoque altera um livro-razão. Nada disso deveria jamais ser algo que você possa executar duas vezes por acidente.

A barreira é lida do comando EFETIVO. Quando um comando envolve outro — como faz o executor genérico do chat —, a barreira vem das flags do comando que vai realmente rodar, não do invólucro. Com uma flag fixa, uma de duas falhas seria inevitável: ou o comando de fatura rodaria sem confirmação, ou toda consulta de país abriria um cartão de confirmação.

read_only e sem barreira não são a mesma coisa. Existem três estados distintos: invoices preview não tem barreira e não grava nada; loads create tem barreira e grava; invoices create não tem barreira, mas grava — um rascunho passa a existir. Um único teste resolve a questão: quando o comando retorna, alguma linha do banco de dados mudou?

Algumas ações não ficam atrás desta barreira porque nem sequer são comandos: comprar um pacote, adicionar um cartão com 3D Secure, aprovar textos legais e encerrar uma conta acontecem no próprio navegador da pessoa. Para essas, lg handoff-links generate retorna um link de logistivo.com — gratuito, sem gravar nada, sem carregar nenhum segredo — e a pessoa conclui a etapa lá. Nenhuma flag, como quer que esteja definida, transforma um pagamento ou um consentimento em uma chamada de API.

É tecnicamente possível que uma integração passe pela barreira automaticamente em toda chamada, mas isso não é recomendável. O padrão certo é automatizar a barreira só para os comandos que você sabe que são reversíveis e encaminhar os irreversíveis para a fila de uma pessoa.

• 1. Chame — Chame o comando com barreira sem confirm. Nada muda.
• 2. Leia o resumo — Você recebe um 409; confirmation.summary no corpo é uma frase escrita para um humano (“About to issue an invoice: X Ltd, 1,200.00 TRY”), não um despejo de argumentos brutos. Comandos monetários também carregam uma prévia estruturada: itens de linha, totais, avisos.
• 3. Confirme — Repita a mesma chamada com confirm: true (--yes na CLI). Comandos irreversíveis são marcados para que rodem no máximo uma vez.

Preflight: veja o que um comando de escrita faria, sem executá-lo

A etapa mais cara ao montar uma ponte com o ERP é descobrir se o seu corpo de requisição está certo executando o comando DE VERDADE: um rascunho de fatura no livro-razão de produção, um crédito queimado, limpeza manual. dry_run acaba com isso — você adiciona um campo à requisição, o comando não roda e você lê o que aconteceria.

Hoje o registro tem 519 comandos; 233 deles apenas leem e não gravam nada. Dos 286 comandos de escrita restantes, 251 têm barreira: chamados sem confirm, eles já respondem 409 e descrevem o que fariam. A lacuna eram os outros 35 — rascunhos de fatura, rascunhos de documentos de exportação, itens de linha: exatamente a cadeia que uma ponte conecta primeiro. Para esses, chamar era fazer.

Havia uma segunda lacuna mesmo nos comandos com barreira: a validação do schema roda DEPOIS da barreira. Assim, uma chamada com um argumento faltando recebia primeiro o cartão de confirmação, confirmava e só então ouvia “este campo está faltando”. Um preflight responde às duas coisas em uma única ida e volta.

E o bug de ponte mais comum — e o descoberto mais tarde — é este: você envia um campo que não está no schema (customer_id onde se espera recipient_contact_id), o servidor o descarta silenciosamente, o comando retorna 200 e o registro vai parar no lugar errado. A resposta do preflight lista esses campos pelo nome em arguments.ignored; nenhuma mensagem de erro jamais fará isso.

Um preflight não grava nada, e isso é estrutural antes de ser uma medição: o caminho do preflight nunca entra no handler do comando, então isso vale para todo comando, inclusive os adicionados depois. Também foi medido quando o recurso foi lançado: toda instrução SQL emitida durante o preflight de todos os comandos de escrita do catálogo daquele momento (dois conjuntos de argumentos, dois perfis, 178 preflights) foi capturada. Nenhum INSERT/UPDATE/DELETE, nenhum job enfileirado, nenhum e-mail; as contagens de linhas em 31 tabelas e o saldo de créditos ficaram inalterados.

O código de saída é o mesmo que a chamada real produziria — rodaria 0, barreira de confirmação 4, conflito de idempotência 2, qualquer outra coisa 1 —, então “lg … --dry-run || exit” é uma barreira significativa em uma etapa de CI.

• 1. Chame com dry_run — Adicione "dry_run": true ao corpo da requisição. A validação, a barreira de perfil e escopo, a resolução do alvo e o cálculo de créditos rodam; o comando, não.
• 2. Leia would_execute — Essa é a única flag na qual basear decisões. Quando ela é false, would_stop.at indica onde uma chamada real pararia: idempotency, target_precheck, confirmation_gate ou arguments.
• 3. Corrija o seu corpo de requisição — arguments.ignored nomeia os campos que seriam descartados silenciosamente, missing_required os obrigatórios que você deixou de fora, e would_charge quantos créditos seriam gastos e se o saldo os cobre.
• 4. Remova o dry_run — Repita até que would_execute seja true; então remova a flag e faça a chamada real. A chave de idempotência que você enviou durante o preflight não foi consumida, então a chamada real roda normalmente.
• O HTTP é sempre 200 — “O comando falharia” nunca chega como 4xx — o próprio preflight teve sucesso e a previsão está no corpo. A exceção é uma recusa de transporte, e aí ele se comporta exatamente como uma chamada real: 404 comando desconhecido, 403 perfil/escopo, 429 rate limit.
• Uma chave com escopo de leitura não pode fazer dry run de um comando de escrita — Ela recebe 403. Um preflight responde “o que acontece se eu chamar isto COM ESTA CHAVE, agora”; dar sinal verde a uma chave de leitura e depois um 403 na chamada real seria exatamente a surpresa que o preflight existe para evitar.
• A chave de idempotência não é consumida — Uma chave enviada durante um preflight não abre nenhuma linha no registro, e um bloqueio expirado não é liberado. Então envie a chave que você pretende usar de verdade: o preflight diz se ela ainda está livre, se repetiria uma execução anterior ou se conflita com outro comando.
• Ele se combina com confirm — Envie dry_run e confirm juntos e a pergunta passa a ser “se eu confirmar, o que acontece?”. Ainda assim, nada roda.
• O preflight em lote é por lote — commands:batch também aceita dry_run, mas a flag pertence ao lote, não a um item (enviá-la em um item gera 422). Você recebe um relatório por item mais o custo total em créditos do lote; um saldo insuficiente é relatado, não recusado.
• Não é de graça — Todo preflight executa consultas reais (prévia, saldo) e conta para o rate limit. Não faça preflight do catálogo inteiro a cada deploy; faça preflight dos comandos que você alterou.

Idempotência: por que repetir não cria duplicatas

Um ERP não lê a sua mensagem de erro, não vê a sua tela e vai reenviar a mesma requisição depois de um timeout. Esta seção existe exatamente por causa desse comportamento.

Uma chamada que carrega um idempotency_key roda no máximo uma vez. A segunda chamada não executa o comando de novo; ela retorna o resultado registrado com o status replayed. Quando a rede cai, quando uma requisição dá timeout ou quando uma fila pega o mesmo job duas vezes, você recebe o primeiro resultado em vez de uma fatura duplicada.

Use uma chave em todo comando de escrita. O campo read_only do catálogo lhe dá essa distinção de graça: todo comando com read_only: false merece uma chave de idempotência.

A sua estratégia de novas tentativas deve usar backoff exponencial e levar a MESMA chave em todas as tentativas. Gerar uma chave nova a cada tentativa é o mesmo que não usar idempotência. Não envie a mesma chave em paralelo: o “no máximo uma vez” é garantido para novas tentativas sequenciais, não para duas requisições disputando entre si.

• Armadilha 1 — a falha também fica travada — Se a primeira execução foi rejeitada por uma regra de negócio (failed), uma segunda chamada com a mesma chave retorna o mesmo erro e o mesmo error_key, e não tenta de novo. Corrigir o argumento e tentar novamente exige uma chave NOVA. Uma chave representa uma tentativa, não uma intenção.
• Armadilha 2 — um resultado grande é repetido sem corpo — O registro só armazena um resultado se ele tiver menos de 64 KB. Um resultado maior é repetido com o status replayed, mas com o corpo vazio. A sua integração deve confiar no sinal “replayed”, e não no corpo, e buscar os dados com o comando get correspondente.
• Armadilha 3 — uma chave pertence a um único comando — Enviar a mesma chave com um comando diferente retorna 409 idempotency_conflict com o conflicting_command; nada roda e nada é repetido. Um cliente que compartilha uma chave entre dois verbos está quebrado, e descobre isso por um erro, não por uma repetição silenciosa.
• Armadilha 4 — o bloqueio dura 24 horas, não para sempre — Depois de 24 horas, a mesma chave é uma nova execução. As novas tentativas de rede chegam em minutos; os números de documentos recorrentes anuais de um ERP não podem ficar “replayed” para sempre. O catálogo publica a janela como idempotency_ttl_hours.
• Armadilha 5 — um erro de servidor não trava a chave — Um 5xx server_error não é uma recusa de negócio: a chave não fica vinculada, então uma nova tentativa com a mesma chave realmente executa o comando. Só failed trava a chave (armadilha 1).
• Escopo e formato — sua empresa, qualquer string, de preferência um UUID — A unicidade é aplicada sobre (sua empresa, chave): o INV-1001 de outro tenant nunca colide com o seu e nunca pode repetir o seu resultado. Use um UUID simples ou um valor composto que seja único por construção, como {ERP-document-no}:{verb}.

Sincronização incremental e paginação

Uma ponte de ERP/CRM deve puxar o que mudou, e não tudo a cada hora. Todo comando de listagem — loads list, demands list-own, contacts list, invoices list, teammates list, load-groups list, reservations list, drivers list, tenders list, products search, warehouses search — aceita dois parâmetros compartilhados e retorna um campo compartilhado.

Por que não existe offset: em uma tabela viva, um offset se desloca. Uma linha inserida entre duas páginas faz você pular ou contar duas vezes um registro, silenciosamente. O cursor só anda para a frente, então um registro inserido ou atualizado no meio do percurso cai no fim da lista: nada se perde, nada se duplica.

Uma carga inicial completa usa o mesmo mecanismo: comece com updated_since=1970-01-01T00:00:00Z e siga o next_cursor até ele ser null. Não existe um endpoint de “exportação” separado, porque nenhum é necessário.

O mesmo com o lg: lg loads list --updated_since=2026-09-01T00:00:00Z --limit=100 --json e, depois, lg loads list --cursor= --json.

Na próxima sincronização, defina updated_since como o maior updated_at que você viu. Os timestamps têm precisão de um segundo, então um registro no limite pode chegar duas vezes — o que é inofensivo, desde que você faça upsert por external_ref ou code do seu lado. Sem updated_since ou cursor, um comando roda em modo de chat: ordenação para humanos, no máximo 20 linhas, next_cursor null e truncated dizendo “há mais”. Não use esse modo para sincronização.

Chaves de erro legíveis por máquina para esta seção: INVALID_CURSOR, INVALID_UPDATED_SINCE, DUPLICATE_EXTERNAL_REF, EXTERNAL_REF_TOO_LONG, EXTERNAL_REF_INVALID. Todas respondem HTTP 422 com error_code: "failed" e result.error_key no corpo. Decida pela chave, nunca pelo texto.

• updated_since — Timestamp ISO-8601 (UTC recomendado, por exemplo 2026-09-01T00:00:00Z). Linhas atualizadas neste instante ou depois dele. Ele coloca o comando em modo de sincronização: ordem fixa (updated_at, id) ascendente, limit limitado a 100.
• cursor — O next_cursor da resposta anterior, literalmente. Ele é opaco e assinado: nunca construa nem edite um, nunca reutilize o cursor de outra empresa ou de outro comando; tudo isso é rejeitado com INVALID_CURSOR.
• limit — Tamanho da página. 1-100 no modo de sincronização (padrão 10).
• next_cursor (resposta) — Cursor para a próxima página. null significa que a lista está completa; é a única resposta correta para “tem mais?”.
• total (resposta) — Linhas que correspondem aos filtros, independentemente da página — para relatórios de progresso.

A sua própria chave: external_ref

Não faça dos nossos ids autoincrementais (invoice_id, contact_id) a chave de negócio no seu ERP; eles são opacos e privados da sua empresa. Cargas, demandas, contatos, faturas, produtos e armazéns carregam a sua chave no lugar deles.

• Defina-a ao gravar — loads create, demands create, contacts create e contacts update, invoices create aceitam um external_ref opcional (máx. 120 caracteres) e o devolvem sem alterações.
• Use-a ao ler — loads get --external_ref=ORD-2026-0917, invoices get --external_ref=..., contacts get --external_ref=..., demands get --external_ref=... funcionam todos; em comandos de listagem e de busca, --external_ref= é um filtro de correspondência exata.
• Única por empresa — Um segundo registro com a mesma chave é recusado com 422 e result.error_key = DUPLICATE_EXTERNAL_REF; a chave de outra empresa responde “não encontrado” para você. A correspondência não diferencia maiúsculas de minúsculas (ord-1 = ORD-1). Um registro arquivado mantém a sua chave; restaure-o antes de reutilizar a chave.
• Envie também um idempotency_key — Uma nova tentativa após um timeout de rede retorna o primeiro resultado em vez de criar uma duplicata. Os dois não são intercambiáveis: external_ref é a sua chave de negócio, idempotency_key identifica uma tentativa.

Webhooks de saída: fazemos um POST para você quando algo acontece

Tudo até aqui era pull: você pergunta, nós respondemos. Uma ponte de ERP precisava perguntar uma vez por minuto para descobrir que uma carga mudou de status, que uma fatura foi emitida ou que uma proposta chegou. Não mais: registre um endereço https, escolha os eventos que lhe interessam, e um POST assinado chega quando eles acontecem.

O push foi adicionado AO LADO do pull, não no lugar dele. A sincronização incremental (updated_since + cursor) continua intacta e ainda é a ferramenta certa: a primeira carga completa, o preenchimento do histórico e a resposta a “perdi alguma coisa?” ficam todos lá. Os webhooks reduzem a latência de minutos para segundos. Uma ponte saudável usa os dois — o webhook como gatilho, a sincronização como rede de segurança.

O payload é um SINAL, não uma cópia do registro. Ele carrega os identificadores (id, o seu próprio external_ref, status, horário); você busca o detalhe com a sua própria chave via GET, e essa chamada já passa pelas suas próprias barreiras de autorização. A superfície de exposição, portanto, fica no nível dos identificadores. Dois campos estão ausentes de propósito: a identidade da empresa que enviou uma proposta (propostas cegas aparecem sob um pseudônimo no painel; colocar a identidade em um webhook furaria essa privacidade por um segundo canal) e os dados de contato de reservas (não há necessidade de mover dados pessoais por um canal extra).

Os nomes de eventos são CONGELADOS. Se o significado de um nome muda, um novo nome é aberto e o antigo continua vivo durante uma janela de descontinuação. Adicionar um novo campo ao payload NÃO incrementa a versão do contrato — um consumidor deve ignorar os campos que não conhece.

• GET /api/common/integration-webhooks — O registro, mais o catálogo de eventos, os limites e os nomes dos headers. Cada linha carrega o seu motivo de silenciamento e um resumo de entregas de 7 dias.
• POST /api/common/integration-webhooks — 201 + { webhook, secret, shown_once: true }. O segredo aparece apenas aqui.
• PATCH /api/common/integration-webhooks/{uuid} — Nome / endereço / eventos / flag de ativo. NÃO mexe no segredo.
• DELETE /api/common/integration-webhooks/{uuid} — Remove a inscrição: a linha sofre soft delete (o histórico continua consultável) e as entregas pendentes são canceladas.
• POST /api/common/integration-webhooks/{uuid}/rotate-secret — 201 + um novo segredo. O valor antigo para de funcionar nesse momento.
• POST /api/common/integration-webhooks/{uuid}/test — Um evento ping — assinatura real, caminho real, cronograma real de novas tentativas.
• GET /api/common/integration-webhooks/{uuid}/deliveries — As entregas mais recentes: status, número da tentativa, código HTTP, duração, etiqueta de erro.
• POST /api/common/integration-webhooks/deliveries/{uuid}/replay — Reenvia uma única entrega: o event_id é PRESERVADO, o id da entrega é novo e o payload é copiado literalmente.

Catálogo de eventos

Cada um dos 13 eventos abaixo é respaldado por uma classe de evento que é REALMENTE disparada. Não há nomes do tipo “seria bom ter” no catálogo: um evento anunciado mas nunca disparado é um evento pelo qual o integrador espera para sempre, e essa falha é silenciosa. Esta tabela também não é escrita à mão — ela é montada a partir do catálogo ao vivo a cada carregamento da página.

invoice.payment_recorded está AUSENTE de propósito: essa classe de evento existe no código, mas não é disparada de lugar nenhum. O evento de pagamento será adicionado no dia em que a classe for disparada de verdade — não antes. Anunciar um evento antes da hora é pior do que nunca adicioná-lo.

• 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)

Verificando a assinatura

Toda requisição carrega um header X-Logistivo-Signature: t=,v1=. A string assinada é "." e o algoritmo é HMAC-SHA256. O prefixo v1 mantém o esquema versionável: se um dia surgir um segundo esquema, o header carregará t=…,v1=…,v2=… e você escolhe o que conhece.

Publicamos dois receptores de referência sem dependências, um para Node e outro para PHP puro. Ambos aplicam as quatro regras acima e se testam com --selftest: assinatura válida, corpo adulterado, segredo errado, timestamp fora da janela, header malformado, a armadilha da re-serialização e os dois tipos de repetição (mesma entrega / mesmo fato). O verificador é a contraparte exata do código que nós mesmos usamos — consumimos o contrato que publicamos.

• Verifique o corpo BRUTO — A assinatura é calculada sobre bytes. Decodificar e serializar de novo o corpo (JSON.stringify(req.body), json_encode($request->all())) transforma os mesmos DADOS em BYTES diferentes, e a assinatura deixa de bater. No Node, a armadilha é a formatação de números (1.50 na transmissão vira 1.5; inteiros grandes perdem precisão); no PHP, é o escape de caracteres (/ vira \/, İ vira \u0130). Use express.raw no Express e $request->getContent() no Laravel. Este é o erro mais comum de todos ao escrever um receptor.
• Verifique o timestamp — t fica DENTRO da assinatura. Verificar apenas a assinatura permite que qualquer pessoa que tenha capturado uma requisição válida a repita horas depois, e o receptor a contaria como um evento verificado. Descarte qualquer requisição em que |agora − t| > tolerância, mesmo que a assinatura esteja correta. A janela recomendada é de 300 segundos.
• Compare em tempo constante — hash_equals / timingSafeEqual. Comparar com == permite que um atacante adivinhe a assinatura byte a byte.
• Elimine duplicatas por event_id, não por id — event_id identifica o FATO: ele é o mesmo para dois inscritos que recebem o mesmo evento e é PRESERVADO no reenvio. id (= X-Logistivo-Delivery) identifica a ENTREGA e muda no reenvio. Responda a “já tratei isto?” com event_id; respondê-la com id faz um reenvio executar o mesmo trabalho duas vezes.

Entrega, novas tentativas e silenciamento

O seu receptor nem sempre estará no ar. O trilho parte desse pressuposto: uma falha transitória entra no cronograma de novas tentativas, uma permanente silencia a inscrição — e o MOTIVO do silenciamento é sempre registrado.

O motivo do silenciamento é legível por máquina e estável (delivery_failures, endpoint_gone, unsafe_target, key_revoked, by_user) e aparece tanto no painel quanto em `lg webhooks list`. Silenciar sem um motivo deixaria sem resposta a pergunta “por que nada está chegando?”. Reativar zera o contador e o carimbo.

Você escreve o endereço; o NOSSO servidor faz a requisição. Sem uma barreira, um tenant que informasse um endereço de metadados da nuvem poderia nos fazer emitir requisições de dentro da nossa própria rede. Por isso, o endereço é verificado tanto no cadastro quanto em CADA entrega:

• Timeouts — 8 s no total, 4 s para conectar — um receptor lento não pode ocupar um worker. Coloque o trabalho em fila e retorne 2xx imediatamente.
• Cronograma de novas tentativas — 60 · 300 · 1800 · 7200 · 21600 segundos → 6 tentativas, uma janela de aproximadamente 8,6 horas.
• A única falha permanente: 410 Gone — Significa “me apague”: sem nova tentativa, a inscrição é silenciada na hora. NUNCA retorne 410 para uma falha de assinatura.
• Todas as outras falhas — TODAS elas recebem novas tentativas, 4xx inclusive. Perder um evento de negócio custa mais do que algumas requisições extras: um receptor que retorna 403 enquanto uma regra de WAF está sendo atualizada perderia silenciosamente um evento de “fatura emitida” em um trilho que tratasse 4xx como permanente.
• Retry-After — Respeitado em 429 e 503 (limitado a 6 horas).
• Redirecionamentos — NÃO são seguidos. Pular para um endereço interno por meio de um 302 furaria a barreira de endereços por uma segunda rota.
• Silenciamento automático — Após 10 entregas consecutivas esgotadas. Um 410, um destino inseguro e a revogação da chave de integração vinculada silenciam IMEDIATAMENTE.
• somente https, somente as portas 443/8443, credenciais embutidas (https://user:pass@…) são rejeitadas;
• localhost, nomes de rótulo único e sufixos internos como .internal / .local / .svc são rejeitados — a intenção é rejeitada antes mesmo de se olhar o resultado da resolução, então um DNS split-horizon não consegue furar a barreira;
• literais de IP e TODOS os registros da resolução DNS precisam ser públicos. Se um nome resolve ao mesmo tempo para um endereço público e para um privado, ninguém nos pergunta qual escolher → o nome é rejeitado de vez;
• no momento da entrega, o endereço é resolvido uma vez e a conexão é fixada no endereço verificado: a janela de DNS rebinding fica fechada;
• o CORPO da resposta do receptor nunca é armazenado em lugar nenhum (só o código de status, a duração e uma etiqueta curta de erro) — assim, o caminho de “leitura”, que é o que de fato daria valor a uma brecha na barreira de endereços, continua fechado.
• De propósito, NÃO existe uma opção de configuração para “permitir endereços privados”: uma opção dessas acaba ficando ligada por acidente algum dia.
• Devolvido UMA única vez, apenas quando a inscrição é criada e no rotate-secret. Ele é armazenado criptografado no servidor e nunca pode ser lido de volta; não existe “mostrar de novo”.
• O lg o imprime na tela e o deixa lá — ele não o grava em nenhum arquivo de configuração ou de cache.
• Se ele se perder, você o rotaciona; o valor antigo para de funcionar NAQUELE MOMENTO. Para uma troca sem interrupção, o seu receptor deve tentar os dois segredos durante a transição.
• Mudar o endereço NÃO mexe no segredo: uma manutenção de rotina como “a URL mudou” não pode quebrar a verificação do lado receptor.

Saúde e status: ninguém deve perceber uma ponte silenciosa antes de você

Uma ponte de integração raramente morre fazendo barulho. Normalmente ela fica em silêncio de madrugada: um token expira, a pessoa em nome de quem a chave roda sai da equipe, um escopo é restringido ou o endpoint receptor começa a retornar 403. Quem percebe primeiro é quase sempre o cliente. lg status existe para inverter essa ordem.

Um único comando responde a duas perguntas ao mesmo tempo, porque durante uma pane as duas são feitas no mesmo instante: a plataforma está no ar, e a minha ponte está saudável? A linha da plataforma funciona sem token — durante uma falha, o próprio token é o primeiro suspeito, e amarrar a pergunta de status a ele deixaria você sem resposta justamente quando você precisa de uma.

O resumo de saúde não mantém nenhum registro novo; ele junta três fontes existentes em uma única frase: o contador de uso diário (quanto você chamou e quanto falhou), o registro de requisições (qual requisição, quando e por que foi rejeitada) e o registro de entregas de webhooks de saída (o evento chegou ao receptor?). A taxa de erro é sempre lida do contador diário; o registro detalhado tem um limite e diz isso com clareza quando o limite é atingido.

O mesmo resumo aparece no painel: em Settings › Integration › Keys, cada linha carrega um selo e, abaixo dele, o motivo. Os limiares não são calculados no cliente; o nível que o servidor atribuiu é o que tanto o painel quanto o lg status pintam, então as duas telas nunca podem dizer coisas diferentes sobre a mesma chave.

O seu watchdog não precisa de token. O endpoint retorna apenas palavras de status; ele não carrega versão, nome de host, nome de fila, contagem de jobs, texto de erro nem dados de clientes — e nem pode carregar.

O resumo de saúde é produzido com um número constante de consultas por requisição; a contagem de consultas não cresce com o número de chaves. Para detalhes, leia as requisições recentes daquela chave com lg logs e a ponte de saída com lg webhooks list.

• SAUDÁVEL — Nenhuma falha medida e temos prova de sucesso: uma chamada bem-sucedida no registro, ou tráfego que permaneceu sem erros no contador.
• ATENÇÃO — Algo começou a quebrar: a taxa de erro ou a sequência de falhas consecutivas ultrapassou um limiar, requisições estão sendo rejeitadas na barreira, a chave está perto de expirar, ou uma ponte que se comunicava regularmente ficou em silêncio.
• FALHANDO — A ponte não está funcionando agora: o token foi revogado sem querer, uma chave encerrada continua sendo chamada, há cinco falhas seguidas, a taxa de erro está acima de cinquenta por cento ou uma inscrição de webhook foi silenciada.
• ENCERRADA — A chave foi encerrada deliberadamente e ninguém a está chamando. Isso é uma decisão, não uma falha — e não é pintado de vermelho.
• SEM DADOS — Não há medição: a chave nunca foi chamada, ou a própria medição falhou. Nenhum dos dois casos é verde.
• Nada de verde falso. O selo de saudável exige prova medida de sucesso; uma chave que nunca foi chamada nunca fica verde, porque nenhuma medição mostra que ela funciona.
• Nada de vermelho falso. Chaves que você encerrou de propósito aparecem como Encerrada. Pintar tudo de vermelho tira o significado do vermelho; uma chave encerrada só fica vermelha se continuar sendo chamada depois do encerramento — e aí, sim, uma ponte está realmente quebrada.
• Não foi possível medir não é o mesmo que sem dados. Se uma consulta falha do lado do servidor, a linha não mostra zero discretamente; ela diz que a medição não pôde ser feita.
• O silêncio é sempre relatado, mas nunca transformado cegamente em aviso. Uma ponte de fechamento de mês que fica em silêncio por trinta horas é normal; uma ponte que se comunicou em pelo menos cinco dos últimos sete dias e fica em silêncio é uma falha. O ritmo é medido, não presumido.
• A própria consulta de status não polui os números de saúde. As chamadas feitas pelo lg status aparecem no registro de requisições, mas são excluídas do cálculo de saúde — caso contrário, a sua própria consulta de status bem-sucedida zeraria a sequência de falhas e esconderia justamente a falha que a tela existe para mostrar.
• Cada linha é medida: uma consulta real é executada no banco de dados, o catálogo de comandos é realmente montado, o registro ao vivo do worker da fila é realmente lido. Nada é presumido.
• A própria resposta também é uma medição: se você consegue ler o corpo, a camada web está no ar.
• O nível superior deriva apenas dos componentes obrigatórios. Quando a fila para, a resposta é degraded, e não down — uma chamada de API síncrona não precisa da fila, e declarar a plataforma fora do ar seria um alarme falso.
• Quando o estado da fila não pode ser medido, o nível superior fica intacto: não saber não é o mesmo que medir que algo está quebrado.
• Se a plataforma estiver fora do ar, o endpoint retorna HTTP 503. O corpo não tem envelope, para que ferramentas de monitoramento possam disparar alertas sem interpretá-lo, e a resposta nunca é armazenada em nenhum cache.

Erros e códigos de saída

Aquilo em que uma máquina se baseia para decidir é uma string estável. O texto do campo error é dirigido a um humano, é localizado e muda sem aviso — uma integração que decide com base no texto da mensagem não é suportada, e a quebra dela não é um bug.

Duas taxonomias, dois campos. error_code é a camada de transporte (a tabela acima) e é o que você verifica primeiro. error_key é a chave estável de regra de negócio dentro de failed — INSUFFICIENT_CREDITS, NOT_FOUND, DUPLICATE_CONTACT, INSUFFICIENT_STOCK — publicada como dicionário no catálogo (error_keys) e abaixo. Um comando que ainda não emite uma chave retorna error_key: null; trate uma chave ausente do dicionário como uma falha genérica.

• ok — HTTP 200 · error_code — · CLI 0 · —
• replayed — HTTP 200 · error_code — · CLI 0 · Repetição idempotente; o trabalho NÃO rodou de novo.
• failed — HTTP 422 · error_code failed · CLI 1 · Não — uma regra de negócio a rejeitou (veja error_key). Inútil até o argumento mudar.
• needs_confirmation — HTTP 409 · error_code needs_confirmation · CLI 4 · Sim, com confirm: true.
• idempotency_conflict — HTTP 409 · error_code idempotency_conflict · CLI 2 · Não — a chave foi usada primeiro para um comando diferente (conflicting_command). Gere uma nova chave.
• forbidden — HTTP 403 · error_code forbidden · CLI 3 · Não — barreira de perfil, ou uma chave com escopo de leitura em um comando de escrita.
• not_found — HTTP 404 · error_code not_found · CLI 2 · Não — nome de comando errado ou removido.
• (schema) — HTTP 422 · error_code invalid_request · CLI 2 · Não — o corpo da requisição ou um argumento falhou na validação do schema (errors{}); não é uma regra de negócio.
• server_error — HTTP 500 · error_code server_error · CLI 6 · Sim — backoff exponencial com a MESMA chave de idempotência; a chave não foi travada.
• 401 unauthenticated — O token expirou ou foi revogado. Tentar de novo não vai ajudar; o token precisa ser substituído.
• 429 rate_limited — Rate limit atingido para este token. A resposta sempre carrega Retry-After e um corpo com retry_after, limit e bucket; respeite-o em vez de inventar um atraso fixo. O lg espera e tenta de novo até três vezes; depois, sai com código 5.
• 5xx server_error / erro de rede — Tente de novo com backoff exponencial e a MESMA chave de idempotência. Trocar a chave executa de novo um trabalho que o servidor pode já ter concluído. O lg tenta de novo três vezes (1 s, 2 s, 4 s) e depois sai com código 6, com error_code network_error ou server_error.

Promessa de estabilidade

A pergunta mais cara em um contrato de integração é “o código que eu escrevo hoje ainda vai rodar amanhã?”. Um único número responde: contract_version no catálogo e o header X-Contract-Version em toda resposta. Ele responde exatamente a uma pergunta — um código escrito antes ainda roda sem alterações? Se o número não aumentou, sim. Se aumentou, não: algo de que você dependia foi removido ou restringido.

Porque um anúncio não remove nada: o seu código existente roda exatamente como antes, no dia seguinte. Incrementar a versão no anúncio emitiria dois sinais para uma única mudança e treinaria você a ignorar o primeiro — enfraquecendo o sinal que realmente importa. O anúncio já vem junto com a chamada que você está fazendo: deprecated_at e replaced_by na linha do catálogo, um header X-Deprecated mais um bloco deprecated na resposta daquele comando e um aviso de uma linha no stderr se você usa o lg. Você não precisa fazer nada para saber que algo vai deixar de existir; isso já está no seu log.

Pelo menos dois trimestres do calendário se passam entre o anúncio e a remoção. Durante toda a janela, o comando antigo ainda responde e avisa a cada chamada. Quando um nome da CLI é aposentado, o seu sucessor assume esse nome como alias: durante a janela, o nome antigo chega ao comando antigo e, no dia em que ele é removido, a mesma chamada cai no novo — sem que você precise lançar uma nova versão do cliente.

preview_invoice → get_invoice (anunciada em 3 de setembro de 2026). get_invoice retorna o mesmo bloco de prévia e acrescenta os itens de linha, o detalhamento de impostos, os pagamentos registrados, o saldo restante e o endereçamento pela sua própria chave de ERP (external_ref). preview_invoice continua funcionando, assim como lg invoices preview — ambos avisam.

• sem alteração — Um novo comando · um novo parâmetro OPCIONAL · um novo campo de resposta · uma nova chave de erro · um novo endpoint — Não faça nada. Você deve ignorar os campos que não conhece; um parser que falha diante de um campo desconhecido não está em conformidade.
• sem alteração — Um ANÚNCIO de descontinuação: aviso de que um comando vai deixar de existir — O seu código continua rodando. Coloque uma tarefa na sua agenda — a janela é de pelo menos 6 meses.
• aumenta — Remover um comando · aposentar um nome antigo da CLI · retirar um campo de resposta · tornar obrigatório um parâmetro opcional · restringir um enum — Significa que você perdeu a janela; o aviso chegou até você em três lugares diferentes.
• O nome de API de um comando (como list_loads) está congelado para sempre; é o nome que você usa nas chamadas HTTP.
• error_code (transporte) e error_key (regra de negócio) são strings estáveis. Novas chaves podem aparecer — trate uma chave que você não encontra no dicionário como uma falha genérica, não como uma quebra.
• O mapeamento entre o status HTTP e o campo status no corpo é fixo.
• O número da versão nunca diminui e pode ser lido em toda resposta — inclusive nos 304 e 429 sem corpo.
• O TEXTO de erros e descrições. Ele é localizado e muda sem aviso; decidir com base no texto da mensagem não é suportado.
• A ausência de campos que você não conhece. Adicionar um campo não incrementa a versão.
• Ids autoincrementais como chaves de negócio. Leve a sua própria chave com external_ref.
• Chaves de erro dinâmicas derivadas de nomes de classes; elas não fazem parte do contrato.

Tabela de identidade dos comandos

A tabela abaixo não é escrita à mão: ela é gerada a partir do registro de comandos ao vivo toda vez que esta página é servida. Um comando adicionado no servidor aparece aqui sozinho. A coluna “Barreira” diz se um comando pede confirmação e se o seu efeito pode ser desfeito; a coluna “Perfis” diz quais tipos de conta vão encontrá-lo no seu catálogo. Selos marcam os comandos que precisam de uma chave de nível manager, os que recebem um arquivo e os que só rodam a partir do lg.

O nome na API (list_loads) está congelado e não vai mudar; é o nome que você usa nas chamadas HTTP. A identidade na CLI (loads list) é regida pela política de versionamento: depois de anunciada, ela só muda com um incremento de versão e uma janela de migração, durante a qual o catálogo serve o par antigo como alias. As descrições aqui vêm do próprio registro de cada comando e estão encurtadas — para o texto completo, os tipos de parâmetros e os valores de enum, leia o endpoint do catálogo ou execute lg help . Comandos exclusivos de afiliados não são listados aqui; uma conta de afiliado os vê no seu próprio catálogo.

• lg account-settings get — Read the account settings (Settings → Account): the company display name (and legal name, read-only), the signed-in user's own name and e-mail (e-mail is read-only here), the saved load code prefix and how the company… (leitura · — · embarcador · API: get_account_settings) [chave manager]
• lg account-settings update — Change account settings (Settings → Account): company_name (the company's display name, company-wide), first_name / last_name (the signed-in user's own name — when only one is given the other part is kept),… (escrita · confirmação · embarcador · API: update_account_settings) [chave manager]
• lg accounting-settings get — Read the company's accounting and invoicing settings and say whether they are set up (muhasebe ayarları, fatura ayarları, e-fatura / e-invoice profile, KDV / VAT tax regime, fatura numaralandırma serisi / invoice… (leitura · — · todos · API: get_accounting_settings)
• lg accounting-settings set-status — Turn the company's accounting module on or off (muhasebe modülünü aç/kapa). (escrita · confirmação · todos · API: set_accounting_module)
• lg accounting-settings update — Update the company's accounting/invoicing settings (muhasebe ve fatura ayarlarını değiştir): legal name, default currency, provider (local/parasut), country, tax regime (KDV/VAT/GST/none), default invoice line… (escrita · confirmação · todos · API: update_accounting_settings)
• lg addresses list — Loading and delivery addresses already used on this company's previous loads (newest first): address_id, name, street, city and country. query filters by name, street or city. limit 1-50 (default 20). (leitura · — · todos · API: list_worked_addresses)
• lg addresses search — Find a place for a route plan stop: the company's own address book first, then a geocoder (counted against the daily routing allowance) when the book has fewer than 3 hits. (leitura · — · transportadora · API: lookup_address)
• lg ai-settings get — Read our company's AI switches (Settings → AI), e.g. ai_file_classify ("AI document analysis"): whether files posted into our load chats are read by AI, sorted into document types and split into company documents, or… (leitura · — · embarcador · API: get_ai_settings) [chave manager]
• lg ai-settings update — Turn our company's AI switches on or off (Settings → AI) — e.g. "stop AI from analysing the files in our load chats" → settings=[{"slug":"ai_file_classify","enabled":false}]. settings is a list of {slug, enabled}; slugs… (escrita · confirmação · embarcador · API: update_ai_settings) [chave manager]
• lg announcements list — Show the system announcements Logistivo sent to this user (new features, maintenance, policy changes) — newest first. (leitura · — · todos · API: list_announcements)
• lg announcements mark-read — Mark system announcements as read for this user. (escrita · — · todos · API: mark_announcements_read)
• lg attachments get — Read a file the user attached to THIS conversation (listed in the user message as [Attachments] with their attachment_uuid). (leitura · — · todos · API: read_attachment) [recebe um arquivo: attachment_uuid]
• lg background-jobs get — Check a background job that another command queued and returned a job_id for (document consistency re-analysis, file classification, tariff inquiry, tariff invoice reading, receipt pack…): status pending / running /… (leitura · — · todos · API: get_background_job)
• lg bank-accounts create — Add one of YOUR OWN company bank accounts to the account book (the accounts you get paid into). (escrita · confirmação + irreversível · todos · API: create_company_bank_account) [chave manager]
• lg bank-accounts delete — Delete one of OUR OWN company bank accounts (for example a closed account). (escrita · confirmação + irreversível · todos · API: delete_company_bank_account) [chave manager]
• lg bank-accounts extract — Read a supplier's bank accounts (IBAN, bank, holder, currency) from one of ITS invoices and save them on that business contact. (escrita · confirmação + irreversível · todos · API: extract_supplier_bank_accounts) [recebe um arquivo: attachment_uuid]
• lg bank-accounts list — List bank accounts. (leitura · — · todos · API: list_bank_accounts)
• lg bank-accounts preview — Check an IBAN without saving anything: is it valid (country, length, checksum) and which bank it belongs to (detected offline from the bank code where known). (leitura · — · todos · API: preview_bank_account_iban)
• lg bank-accounts set-default — Make one of OUR OWN bank accounts the default — the IBAN printed on our invoices and e-invoices. (escrita · confirmação + irreversível · todos · API: set_default_company_bank_account) [chave manager]
• lg bank-accounts set-status — Confirm or reject a bank account that was read from a document by AI or written by an integration — your own account or a business contact's account (find the ones waiting with list_bank_accounts… (escrita · confirmação + irreversível · todos · API: decide_bank_account_verification) [chave manager]
• lg bank-accounts update — Update one of OUR OWN company bank accounts (the accounts customers pay us into): IBAN, bank, account holder, branch code, account number or currency. (escrita · confirmação + irreversível · todos · API: update_company_bank_account) [chave manager]
• lg banks list — List the banks of Turkey with their bank_id and SWIFT/BIC code — the bank_id that create_company_bank_account and update_company_bank_account need. (leitura · — · todos · API: list_banks)
• lg bids accept — Accept a carrier's bid on one of this company's demands. (escrita · confirmação + irreversível · embarcador · API: accept_demand_bid)
• lg bids calculate — Before bidding: what this carrier would earn and how many credits a bid would cost if the customer accepts it. (leitura · — · transportadora · API: calculate_bid_earnings)
• lg bids cancel — Withdraw (geri çek) one of THIS carrier company's PENDING bids. (escrita · confirmação + irreversível · transportadora · API: cancel_demand_bid)
• lg bids create — Submit a bid (teklif ver) on an open demand. amount_per_vehicle is the freight PER VEHICLE, not the total. (escrita · confirmação + irreversível · transportadora · API: create_demand_bid)
• lg bids get — Detail of ONE bid this carrier company submitted: demand, status (pending / accepted / revised / cancelled / price_too_high), price per vehicle and total, currency, vehicle count, customs included or customs price,… (leitura · — · transportadora · API: get_my_demand_bid)
• lg bids list — List the bids (teklif) THIS carrier company has submitted, newest first, with their outcome. (leitura · — · transportadora · API: list_my_bids)
• lg bids revise — Revise this carrier's own PENDING bid on a demand: the old bid is marked revised and a NEW bid replaces it (it gets a new bid code). (escrita · confirmação + irreversível · transportadora · API: revise_demand_bid)
• lg carbon-reports calculate — Calculate the CO2 emission of an EXISTING load (load_code: weight and route from the load, including its Ro-Ro leg) OR of a route you describe (transport_mode road|roro + weight_kg + departure_address + arrival_address,… (leitura · — · todos · API: calculate_load_carbon_emission)
• lg carbon-reports download — Export ALL of the company's saved CO2 emission reports to one Excel file (one row per report: date, route, mode, weight, distance, emission, factor, method) and return a short-lived download link. (leitura · — · todos · API: export_carbon_emission_reports)
• lg carbon-reports generate — Produce the signed CO2 emission report (PDF, with QR code) for a load OR for a route, save it to the company's report list and return a download link. (escrita · confirmação + irreversível · todos · API: generate_carbon_emission_report)
• lg carbon-reports get — Read one CO2 emission report in full: total emission in kg, transport mode, weight, distance, emission factor, calculation method and source, the departure/arrival addresses, the leg breakdown for multi-modal routes… (leitura · — · todos · API: get_carbon_emission_report)
• lg carbon-reports list — List the CO2 emission reports this company has generated (newest first): report number, file name, who created it and when. (leitura · — · todos · API: list_carbon_emission_reports)
• lg carrier-routes get — This carrier's route definitions (Rota Yönetimi): the countries served — always ↔ Türkiye in both directions — and the vehicle types and load types operated, with ids and names. (leitura · — · transportadora · API: get_carrier_routes)
• lg carrier-routes set — REPLACE this carrier's route definitions (Rota Yönetimi) with the given FULL sets: countries served (each to/from Türkiye, both directions), vehicle types and load types. (escrita · confirmação · transportadora · API: set_carrier_routes) [chave manager]
• lg chart-of-accounts list — List the chart of accounts available to this company (Turkish uniform chart: 100 Kasa, 102 Bankalar, 120 Alıcılar, 320 Satıcılar, 391 Hesaplanan KDV, 600/601 Satışlar…), optionally filtered by code/name text or type. (leitura · — · todos · API: list_chart_of_accounts)
• lg checks assign-invoices — Allocate a pending, field-confirmed cheque to one or more open LOCAL invoices of the same contact and currency: in = sales invoices (collection), out = purchase invoices (payment). (escrita · confirmação + irreversível · todos · API: attach_check_to_invoices) [chave manager]
• lg checks bounce — Record that a cheque BOUNCED (came back unpaid). (escrita · confirmação + irreversível · todos · API: mark_check_bounced)
• lg checks cancel — CANCEL a pending cheque (e.g. registered by mistake, returned before use): no journal entry is written and any invoice reservation is released. (escrita · confirmação + irreversível · todos · API: cancel_settlement_check) [chave manager]
• lg checks collect — Record that a cheque was COLLECTED (money reached the bank for an incoming cheque, or left the bank for an outgoing one) on its due date. (escrita · confirmação + irreversível · todos · API: mark_check_collected)
• lg checks create — Register a cheque in the cheque portfolio. (escrita · confirmação · todos · API: create_settlement_check) [chave manager] [recebe um arquivo: front_attachment_uuid, back_attachment_uuid]
• lg checks get — Read one cheque in full: its identity (number, serial, bank and branch, drawer with tax number, IBAN), the face amount and currency, issue and due dates, the counterparty, the status with every timestamp (executed,… (leitura · — · todos · API: get_settlement_check)
• lg checks list — List the cheque portfolio of this company: cheque number, direction (in = received from a customer, out = given to a supplier), drawer and bank, face amount with its currency, issue and DUE date, the counterparty… (leitura · — · todos · API: list_settlement_checks)
• lg checks remove-invoices — Release a pending cheque's invoice allocation: the reservations are removed (invoices become payable again) and the cheque goes back to the unallocated pending cheques. (escrita · confirmação · todos · API: detach_check_from_invoices) [chave manager]
• lg checks run — EXECUTE a pending, allocated cheque against its invoices: the reservations become payments (the invoice balances close), and the notes receivable (121, received cheque) or notes payable (321, given cheque) journal… (escrita · confirmação + irreversível · todos · API: execute_settlement_check) [chave manager]
• lg checks update — Correct a pending cheque's fields and CONFIRM them — the human sign-off on what AI read from the photo (or on a manual entry). (escrita · confirmação · todos · API: update_settlement_check) [chave manager]
• lg companies add-role — Add a role to this company (firmaya rol ekle): customer (shipper), carrier, customs (customs broker) or affiliate. (escrita · confirmação + irreversível · todos · API: add_company_role) [chave manager]
• lg companies delete-logo — Remove this company's logo (firma logosu) from the branded login portal, documents and the panel. (escrita · confirmação + irreversível · todos · API: delete_company_logo) [chave manager]
• lg companies get — This company's own profile (firma profili): legal name, tax number and tax office, address and postal code, city/country, payment term (vade), the company roles it has (customer/carrier/customs/affiliate) and the roles… (leitura · — · todos · API: get_company_profile)
• lg companies invite — Invite a company that is NOT on Logistivo yet by e-mail (e.g. a carrier we want to give a load to). (escrita · confirmação + irreversível · todos · API: invite_company_to_platform)
• lg companies list — Logistivo platform companies this company has already worked with on loads (shared load chats), by company_type: customer (shippers), carrier or customs (customs brokers). (leitura · — · todos · API: list_platform_companies)
• lg companies search — Check whether a company is on Logistivo — by EXACTLY ONE of: tax_number (exact VKN / tax id), vat_number (exact EU/UK VAT number) or email (any e-mail of that company, matched by its domain; then company_type is… (leitura · — · todos · API: search_platform_companies)
• lg companies set-brand-colors — Set the two colours of this company's branded login portal (markalı giriş portalı, /p//login) — primary_color and secondary_color as #RRGGBB hex. (escrita · confirmação · transportadora, despachante aduaneiro · API: set_company_brand_colors) [chave manager]
• lg companies set-logo — Make an uploaded image this company's logo (firma logosu) — shown on the branded login portal, documents and the panel. attachment_uuid is a JPEG or PNG image (max 8 MB) uploaded to this conversation or with `lg upload`. (escrita · confirmação + irreversível · todos · API: set_company_logo) [chave manager] [recebe um arquivo: attachment_uuid]
• lg companies update — Update this company's profile (firma profili) — send ONLY the fields that change: legal_name (ticaret unvanı), tax_number (VKN / VAT id), tax_branch (vergi dairesi), address_street, postal_code, city_id, country_code… (escrita · confirmação · todos · API: update_company_profile) [chave manager]
• lg company-documents create — File a document the user attached (in this chat, or uploaded to the command surface) as one of the company's own documents (firma evrakı yükle): tax certificate (vergi levhası), signature circulars (imza sirküleri),… (escrita · confirmação · todos · API: upload_company_document) [recebe um arquivo: attachment_uuid]
• lg company-documents delete — Remove one of the company's own documents (tax certificate, signature circular, trade registry gazette, permits…) from its document list — e.g. a wrong or outdated upload. document_id is the one shown by… (escrita · confirmação + irreversível · todos · API: delete_company_document)
• lg company-documents list — List this company's own filed documents (tax certificate, signature circulars, trade registry gazette, contracts, TIO/L2 permits, files uploaded to chats…) with their type, number, validity date and verification status. (leitura · — · todos · API: list_company_documents)
• lg company-documents list-missing — Which company documents (tax certificate, signature circulars, trade registry gazette, TIO/L2/C2 permits …) this company is REQUIRED to have for its company type and country, which of them are on file and verified, and… (leitura · — · todos · API: list_missing_company_documents)
• lg company-domains create — Add an e-mail domain to our company (e.g. firma.com.tr) and e-mail a 6-digit verification code to a mailbox ON that domain. (escrita · confirmação + irreversível · todos · API: create_company_domain) [chave manager]
• lg company-domains delete — Remove one of our UNVERIFIED company domains (e.g. added by mistake). (escrita · confirmação + irreversível · todos · API: delete_company_domain) [chave manager]
• lg company-domains list — List our company's e-mail domains (Company settings → Domains): each row has company_domain_id, domain, verified (true once the 6-digit code was entered) and, for unverified ones, the mailbox the last code was sent to. (leitura · — · todos · API: list_company_domains)
• lg company-domains resend — E-mail a NEW 6-digit verification code for one of our unverified company domains (the previous code stops working). (escrita · confirmação + irreversível · todos · API: resend_company_domain_code) [chave manager]
• lg company-domains verify — Verify one of our unverified company domains with the 6-digit code that was e-mailed to the mailbox on that domain. (escrita · confirmação + irreversível · todos · API: verify_company_domain) [chave manager]
• lg company-relationships accept — Accept a connection proposal another company sent us (relationship_id from list_company_relationships direction=incoming). (escrita · confirmação + irreversível · todos · API: accept_company_relationship) [chave manager]
• lg company-relationships create — Send a connection proposal to link one of our business contacts with its company on the Logistivo platform (company_id from search_platform_companies). (escrita · confirmação + irreversível · todos · API: create_company_relationship) [chave manager]
• lg company-relationships list — List our company connections on the platform (direction=outgoing, default: the connections in our directory, with status and roles such as carrier/customs_broker/supplier) or the connection proposals other companies… (leitura · — · todos · API: list_company_relationships)
• lg company-relationships reject — Reject a connection proposal another company sent us (relationship_id from list_company_relationships direction=incoming). (escrita · confirmação + irreversível · todos · API: reject_company_relationship) [chave manager]
• lg company-relationships revoke — End a company connection we are a party of (either side may end it), or withdraw a pending proposal. (escrita · confirmação + irreversível · todos · API: revoke_company_relationship) [chave manager]
• lg contacts add-address — Add an address to a business contact (e.g. a warehouse or branch): a label, the full street address and the country (ISO-2 code); postal code optional. (escrita · confirmação · todos · API: add_business_contact_address)
• lg contacts add-bank-account — Add a bank account (IBAN) to a business contact so it can be used on payment instructions and invoices. (escrita · confirmação + irreversível · todos · API: add_business_contact_bank_account)
• lg contacts add-person — Add a person (yetkili kişi) to a business contact: first name, last name and e-mail are required; phone, phone country code, job title and a note are optional. (escrita · confirmação · todos · API: add_business_contact_person)
• lg contacts archive — Archive a business contact (cariyi arşivle): it disappears from lists and pickers and becomes read-only, but nothing is deleted — invoices, loads and bank accounts stay linked, and restore_business_contact brings it… (escrita · confirmação · todos · API: archive_business_contact)
• lg contacts create — Create a new business contact (cari) in the company directory. (escrita · confirmação · todos · API: create_business_contact)
• lg contacts delete-address — Delete one of a business contact's addresses. (escrita · confirmação + irreversível · todos · API: delete_business_contact_address)
• lg contacts delete-bank-account — Delete one of a business contact's bank accounts (for example an old or wrong IBAN). (escrita · confirmação + irreversível · todos · API: delete_business_contact_bank_account)
• lg contacts delete-person — Delete a person from a business contact, together with that person's notification preferences. (escrita · confirmação + irreversível · todos · API: delete_business_contact_person)
• lg contacts extract — Read a business card, letterhead or invoice header (image or PDF) and return the company details on it — legal name, tax number and office, VAT number, e-mail, phone, IBAN (checksum-checked, bank detected), address,… (leitura · — · todos · API: extract_business_contact_from_image) [recebe um arquivo: attachment_uuid]
• lg contacts extract-text — Read pasted text (Excel/CSV rows, e-mail signatures, a typed list) and return up to 100 draft records of ONE kind: companies, persons, addresses or bank_accounts. (leitura · — · todos · API: extract_business_contacts_from_text)
• lg contacts get — Read one business contact in full (identity, tax data, address, e-mail/phone, bank accounts, platform link) together with its account summary: ledger balance (positive = they owe us), open receivables and open payables. (leitura · — · todos · API: get_business_contact)
• lg contacts invite — Invite a business contact to join Logistivo by e-mail. (escrita · confirmação + irreversível · todos · API: invite_business_contact)
• lg contacts list — List the company's business contacts (customers, carriers, suppliers, consignees) with optional text search over name, legal name and tax number. (leitura · — · todos · API: list_business_contacts)
• lg contacts list-addresses — List the saved addresses of one business contact (label, street address, postal code, country) with address_id, needed by update/delete. (leitura · — · todos · API: list_business_contact_addresses)
• lg contacts list-person-notifications — Show which load notifications a contact person receives and on which channel (e-mail, push, SMS), plus the notification types that can be chosen with their allowed channels — use those slugs with… (leitura · — · todos · API: list_business_contact_person_notifications)
• lg contacts list-persons — List the people (yetkili kişiler) saved on one business contact: name, e-mail, phone, job title, note, and which load notifications each one receives. (leitura · — · todos · API: list_business_contact_persons)
• lg contacts list-routes — Show which countries a business contact that is linked to a carrier on the platform serves: its declared route pairs (from-country → to-country) and the distinct country list. (leitura · — · todos · API: list_business_contact_routes)
• lg contacts remove-company-link — Remove the link between a business contact and its company on the Logistivo platform. (escrita · confirmação + irreversível · todos · API: unlink_business_contact_company) [chave manager]
• lg contacts restore — Bring an archived business contact back (cariyi arşivden geri al): it returns to lists and pickers and can be edited again. (escrita · confirmação · todos · API: restore_business_contact)
• lg contacts search — Resolve a business contact (customer/partner/recipient) by name, legal name or tax number to its contact_id. (leitura · — · todos · API: lookup_business_contact)
• lg contacts set-default-bank-account — Make one of a business contact's bank accounts its DEFAULT account — the one pre-selected when you pay this contact. (escrita · confirmação + irreversível · todos · API: set_default_business_contact_bank_account)
• lg contacts set-person-notifications — Turn load notifications on or off for a contact person, per notification type and channel (e-mail, push, SMS). (escrita · confirmação · todos · API: set_business_contact_person_notifications)
• lg contacts update — Update fields of an existing business contact. (escrita · confirmação · todos · API: update_business_contact)
• lg contacts update-address — Correct one of a business contact's addresses. (escrita · confirmação · todos · API: update_business_contact_address)
• lg contacts update-bank-account — Correct one of a business contact's bank accounts: IBAN, account holder, bank name, BIC/SWIFT, currency, label, account type, branch code or account number. (escrita · confirmação + irreversível · todos · API: update_business_contact_bank_account)
• lg contacts update-person — Correct a contact person's details. (escrita · confirmação · todos · API: update_business_contact_person)
• lg containers calculate — Decode and validate a container number (konteyner numarası) per ISO 6346 — owner code, category, serial, check digit (is it correct, and what it should be) and, when known, the operating line with its public tracking… (leitura · — · todos · API: decode_container_number)
• lg conversations add-file — Post a file into an OFFER (demand-bid) chat as this user — e.g. a price sheet or a vehicle photo for the other company. conversation_code comes from list_conversations (rows whose subject is demand_bid). (escrita · confirmação + irreversível · todos · API: send_conversation_file) [recebe um arquivo: attachment_uuid]
• lg conversations add-invitation — Invite a person from ANOTHER company into a load chat by e-mail (sohbete dışarıdan davet). (escrita · confirmação + irreversível · todos · API: invite_to_conversation)
• lg conversations add-message — Post a message into a load/bid conversation AS THIS USER (not as an assistant). (escrita · confirmação + irreversível · todos · API: send_conversation_message)
• lg conversations add-participants — Add people to a load/demand conversation (sohbete kişi ekle) — "Ayşe'yi FKZ8515 sohbetine ekle". (escrita · confirmação · todos · API: add_conversation_participants)
• lg conversations create — Open the freight chat with a carrier that bid on one of OUR demands (navlun sohbetini başlat) — bid_code comes from get_demand / the bids of a demand. (escrita · confirmação + irreversível · embarcador · API: start_bid_conversation)
• lg conversations list — List the chat conversations this user is a member of (load chats, bid chats and private carrier channels), newest activity first. (leitura · — · todos · API: list_conversations)
• lg conversations list-files — List the files shared in a load/bid chat, newest first: document type, title, file name, who posted it and when. (leitura · — · todos · API: list_conversation_files)
• lg conversations list-invitations — Show the e-mail invitations to a load chat that have not been accepted yet: who was invited, by whom and when, and what they will be allowed to see. (leitura · — · todos · API: list_conversation_invitations)
• lg conversations list-messages — Read the most recent messages of one conversation — give it a load code (e.g. (leitura · — · todos · API: list_conversation_messages)
• lg conversations list-participants — Who is in this conversation — name and company of every participant. (leitura · — · todos · API: list_conversation_participants)
• lg conversations mark-read — Mark one conversation as read for this user (clears its unread badge), or with all=true every load, bid and direct-message chat at once. (escrita · — · todos · API: mark_conversation_read)
• lg conversations remove-message — Delete one of THIS user's own messages from a conversation (message_id from list_conversation_messages with `mine` true). (escrita · confirmação + irreversível · todos · API: delete_conversation_message)
• lg conversations remove-participant — Remove someone from a load/bid chat, cancel a pending e-mail invitation to it, or leave it yourself (give your own user_id). (escrita · confirmação + irreversível · todos · API: remove_conversation_participant)
• lg conversations update-message — Edit one of THIS user's own messages in a conversation (message_id comes from list_conversation_messages, where `mine` is true). (escrita · confirmação · todos · API: update_conversation_message)
• lg countries search — Resolve a country by name (Turkish, English or the local/native name) or ISO 3166-1 alpha-2 code to its country_id, for the sending/receiving country on a load. (leitura · — · todos · API: lookup_country)
• lg currencies list — The currencies the platform knows (currency_id, code, name, symbol) with the latest exchange rate against the Turkish lira (buying / selling, rate date). currency_id is what forms such as bank accounts take. (leitura · — · todos · API: list_currencies)
• lg custom-reports generate — Custom report counted server-side over ALL records of a dataset: filter, group (dates by month etc.), count/sum/avg/min/max (money per currency) or list rows; format=xlsx|pdf|csv gives a file. (leitura · — · todos · API: build_report)
• lg customs-companies list — Customs broker companies this customer can assign when accepting a bid (accept_demand_bid customs_company_id): the Logistivo customs companies you already work with in your chats. (leitura · — · embarcador · API: list_customs_companies)
• lg customs-locations search — Search customs offices / customs locations (gümrük müdürlüğü, gümrük lokasyonu) by name or street — for the exit and destination customs of a load. (leitura · — · todos · API: lookup_customs_location)
• lg demand-bid-reports get — Bid report across ALL demands at once, counted server-side: for a customer the bids RECEIVED on its demands, for a carrier the bids it PLACED. (leitura · — · embarcador, transportadora · API: get_demand_bid_report)
• lg demand-reports get — Demand report (Talep Raporu) with optional filters: status, demanding company, transport mode, pickup / delivery countries, loading-date window. (leitura · — · embarcador, transportadora · API: get_demand_report)
• lg demand-settings get — This carrier company's demand settings: whether demands opened by forwarder companies reach the company (accept_demands_from_forwarders). (leitura · — · transportadora · API: get_demand_settings) [chave manager]
• lg demand-settings update — Change this carrier company's demand settings. accept_demands_from_forwarders=false stops demands opened by forwarder companies from reaching the company (only shippers' demands remain); true lets them in again. (escrita · confirmação · transportadora · API: update_demand_settings) [chave manager]
• lg demand-targets search — Resolve a pickup/delivery location for a demand to a target token ("5-" = district/postal area, "10-" = seaport address). (leitura · — · embarcador · API: lookup_demand_target)
• lg demands create — Open a freight demand (talep) so carriers can bid. (escrita · confirmação + irreversível · embarcador · API: create_demand) [recebe um arquivo: attachment_uuids]
• lg demands download — File for ONE demand owned by this company. export_type=details_pdf: the demand's detail sheet (route, dates, cargo, pallets) as PDF. export_type=sales_xlsx: the sales report workbook — demand information, every bid… (leitura · — · embarcador · API: download_demand_export)
• lg demands extract — Read a freight request text (an e-mail body, a note, a voice transcript) and return the demand fields it contains in the demand wizard's shape: transport mode, countries, ports, locations, dates, load type, vehicle… (leitura · — · embarcador · API: extract_demand_from_text)
• lg demands get — Detail of ONE freight demand. (leitura · — · embarcador, transportadora · API: get_demand)
• lg demands list — List freight demands (talep) this carrier is allowed to bid on, newest first. (leitura · — · transportadora · API: list_open_demands)
• lg demands list-own — List the freight demands (talep) OWNED by this customer company, newest first, with route, dates, vehicles, status and bid count. (leitura · — · embarcador · API: list_demands)
• lg demands options — Reference lists needed to build a freight demand (talep) with create_demand: vehicle types (id, name, transport mode), payment maturity options (id + days; company_default_maturity_option_id is what the company normally… (leitura · — · embarcador · API: get_demand_form_options)
• lg demands set-status — Close (make passive) one of this company's ACTIVE demands so carriers stop bidding. (escrita · confirmação + irreversível · embarcador · API: close_demand)
• lg demands update — Edit one of this company's ACTIVE demands that has NO bids yet (a demand with bids or a closed one cannot be edited). (escrita · confirmação · embarcador · API: update_demand) [recebe um arquivo: attachment_uuids]
• lg direct-conversations add-message — Send a direct message AS THIS USER (never as an assistant) — either into an existing chat (conversation_code from list_direct_conversations) or to one person (to_user_id from list_direct_message_contacts; their private… (escrita · confirmação + irreversível · todos · API: send_direct_message)
• lg direct-conversations create — Start a direct chat. (escrita · confirmação + irreversível · todos · API: create_direct_conversation)
• lg direct-conversations download — Produce the whole direct-message or group chat as a PDF (the same file as the panel's export button: participants and every message with date and time) and return a short-lived download link. (leitura · — · todos · API: export_direct_conversation_pdf)
• lg direct-conversations list — List this user's direct-message (DM) chats and group chats — person-to-person messaging, separate from load/bid chats (those are list_conversations). (leitura · — · todos · API: list_direct_conversations)
• lg direct-conversations list-contacts — List the people this user can direct-message: their own teammates plus people they share a load/bid chat with. (leitura · — · todos · API: list_direct_message_contacts)
• lg direct-conversations list-messages — Read the latest messages of one direct-message or group chat (conversation_code from list_direct_conversations), oldest→newest, with who wrote them. `mine: true` marks this user's own messages; only those, and only… (leitura · — · todos · API: list_direct_conversation_messages)
• lg direct-conversations mark-read — Mark one direct-message or group chat as read for this user (clears its unread badge). (escrita · — · todos · API: mark_direct_conversation_read)
• lg direct-conversations remove-message — Delete one of THIS user's own direct messages (message_id from list_direct_conversation_messages, mine and editable true), only within 5 minutes of sending. (escrita · confirmação + irreversível · todos · API: delete_direct_message)
• lg direct-conversations update — Rename a GROUP direct chat (private one-to-one chats have no title). (escrita · confirmação · todos · API: rename_direct_conversation)
• lg direct-conversations update-message — Edit one of THIS user's own direct messages (message_id from list_direct_conversation_messages, where mine and editable are true). (escrita · confirmação · todos · API: update_direct_message)
• lg document-checks run — Cross-check documents the user attached to THIS conversation against each other and report the discrepancies: mismatched party names, quantities, weights, amounts, dates, container or reference numbers between an… (escrita · — · todos · API: check_document_compliance) [recebe um arquivo: attachment_uuids]
• lg document-types list — List the platform's document types (slug and name) — the values document_type_slug accepts in upload_company_document, add_driver_document and the vehicle document commands. (leitura · — · todos · API: list_document_types)
• lg documents download — Get a short-lived (15 minute) download/preview link for one document by its document_id (from list_load_documents or list_company_documents). (leitura · — · todos · API: get_document_link)
• lg drive-rest-estimates get — One driver's GPS-ESTIMATED driving/rest status and driving time left under EU 561/2006 / AETR: current activity and since when, driving_left_today_s = the legal driving time left today under the daily, weekly (56 h) AND… (leitura · — · transportadora · API: get_driver_drive_rest_estimate)
• lg drive-rest-estimates list — Fleet overview of the GPS-ESTIMATED driving/rest status and driving time left (EU 561/2006 / AETR): per driver the current activity, driving_left_today_s = the legal driving time left today under the daily, weekly (56… (leitura · — · transportadora · API: list_driver_drive_rest_estimates)
• lg driver-accounts get — Answer "how much do we owe this driver / how much does the driver owe us". (leitura · — · embarcador, transportadora · API: get_driver_account_summary)
• lg driver-accounts list-candidates — Before opening or filling a driver settlement statement: which of ONE driver's receipts and advances can go on it, and why the others cannot. (leitura · — · embarcador, transportadora · API: list_driver_account_candidates)
• lg driver-advances cancel — Cancel (void) a recorded driver money movement that did not really happen or was entered with the wrong amount. (escrita · confirmação + irreversível · embarcador, transportadora · API: cancel_driver_advance)
• lg driver-advances create — Record a money movement between the company and a driver: an advance handed to the driver, money the driver gave back, a closing payout, or a carry-forward opening balance. (escrita · confirmação · embarcador, transportadora · API: create_driver_advance) [recebe um arquivo: attachment_uuid]
• lg driver-advances delete — Delete a driver money movement that was entered by mistake (duplicate, wrong driver). (escrita · confirmação + irreversível · embarcador, transportadora · API: delete_driver_advance)
• lg driver-advances list — List the money movements between the company and its drivers: cash advances handed out, money paid back by the driver, closing payouts and carry-forward opening balances. (leitura · — · embarcador, transportadora · API: list_driver_advances)
• lg driver-advances update — Correct the non-money details of a recorded driver money movement: its reference, note, or the load it belongs to. (escrita · confirmação · embarcador, transportadora · API: update_driver_advance)
• lg driver-availabilities create — Record that a driver is unavailable on some days — "Ali is on leave 14-20 November", "Mehmet rests at home next week", "Kemal is sick from today". (escrita · confirmação · transportadora · API: create_driver_availability)
• lg driver-availabilities delete — Delete ONE availability period (id from list_driver_availabilities) — the driver counts as available again on those days. (escrita · confirmação + irreversível · transportadora · API: delete_driver_availability)
• lg driver-availabilities list — List drivers' leave, home-rest, sick and other unavailability periods (newest planning input), optionally for one driver and/or a date window. (leitura · — · transportadora · API: list_driver_availabilities)
• lg driver-availabilities update — Correct one availability period (id from list_driver_availabilities): kind, dates, Schengen presence or note. (escrita · confirmação · transportadora · API: update_driver_availability)
• lg driver-expense-settings get — Read this company's driver expense module settings: is the module switched on, which currency receipts and advances are converted into, whether receipts need approval (and above which amount), whether drivers may… (leitura · — · embarcador, transportadora · API: get_driver_expense_settings)
• lg driver-expense-settings update — Change this company's driver expense module settings — only the fields you pass change. (escrita · confirmação · embarcador, transportadora · API: update_driver_expense_settings) [chave manager]
• lg driver-expenses create — File one or MANY expense receipts the user attached to this conversation (fuel, toll, ferry, parking, repair, meal…) into the driver expense ledger as pending expenses of ONE of this company's drivers. (escrita · confirmação + irreversível · embarcador, transportadora · API: process_receipt) [recebe um arquivo: attachment_uuid, attachment_uuids]
• lg driver-expenses declare — Record a driver expense WITHOUT a receipt (fişsiz şoför harcaması) — "Mehmet dün 40 EUR otopark ödedi, fişi yok", "log 120 PLN toll for driver X". (escrita · confirmação · embarcador, transportadora · API: create_driver_expense)
• lg driver-expenses delete — Delete a driver expense entered by mistake (duplicate receipt, wrong driver, test entry). (escrita · confirmação + irreversível · embarcador, transportadora · API: delete_driver_expense)
• lg driver-expenses download — Get the download link of a receipt pack that generate_driver_receipt_pack prepared in the background. (leitura · — · embarcador, transportadora · API: download_driver_receipt_pack)
• lg driver-expenses generate — Produce ONE PDF that contains the driver receipts of a selection — for a trip, a load, a driver statement or a date window — e.g. to hand to accounting or the customer. (leitura · — · embarcador, transportadora · API: generate_driver_receipt_pack)
• lg driver-expenses get — Read one driver expense (receipt) by its id: merchant, amount, currency, converted amount, category, payment channel, whether it is charged to the driver, and the approval status. (leitura · — · embarcador, transportadora · API: get_driver_expense)
• lg driver-expenses list — List driver expense receipts (fuel, toll, ferry, parking, food, repair…) with a converted total. (leitura · — · embarcador, transportadora · API: list_driver_expenses)
• lg driver-expenses list-loads — For ONE driver: which loads they carried and, per load, how many receipts there are, how many still await approval, how much is reimbursable to the driver, how much is company-billed (fuel card / DKV / UTA — never the… (leitura · — · embarcador, transportadora · API: list_driver_expense_loads)
• lg driver-expenses list-trips — For ONE driver: which trips (load groups) they drove and, per trip, the number of loads and the driver's OWN receipt figures (count, awaiting approval, reimbursable, company-billed fuel-card / DKV / UTA, still… (leitura · — · embarcador, transportadora · API: list_driver_expense_trips)
• lg driver-expenses review — Approve or reject ONE driver expense (receipt) from the chat, or send an already-decided one back to pending. status=approved means the company accepts the expense (an approved reimbursable receipt can then be counted… (escrita · confirmação · embarcador, transportadora · API: review_driver_expense)
• lg driver-expenses set-in-account — Count driver receipts INTO the driver's account (include=true, default) or take them OUT of it (include=false). (escrita · confirmação · embarcador, transportadora · API: set_driver_expenses_in_account)
• lg driver-expenses update — Correct a recorded driver expense (receipt or no-receipt): amount, currency, date, category, how it was paid, merchant, description or the load it belongs to — "the parking was 45 EUR not 40", "that fuel was paid with… (escrita · confirmação · embarcador, transportadora · API: update_driver_expense)
• lg driver-expenses update-conversion — Retry the currency conversion of ONE driver receipt whose exchange rate could not be resolved (it then sits outside every total and cannot go into a driver statement). (escrita · — · embarcador, transportadora · API: retry_driver_expense_conversion)
• lg driver-schedules accept — Apply ONE schedule suggestion (suggestion_id from get_driver_schedule): the proposed driver is assigned to the load (or every consignment of the trip — consignments still held by another driver are taken over, and the… (escrita · confirmação · transportadora · API: apply_driver_schedule_suggestion)
• lg driver-schedules generate — Compute schedule suggestions for a 7-90 day window starting within 30 days: which driver should take each unassigned load, trip and route plan so that nobody runs out of Schengen days, leave is respected and vehicles do… (escrita · confirmação · transportadora · API: generate_driver_schedule)
• lg driver-schedules get — Read one schedule run (schedule_id from generate_driver_schedule / list_driver_schedules): summary (jobs covered, unassignable jobs and why, vehicle idle days before → after, lowest Schengen margin), the suggestions in… (leitura · — · transportadora · API: get_driver_schedule)
• lg driver-schedules list — List the company's schedule-suggestion runs, newest first: id (schedule_id), status (queued | running | completed | failed), the planned window, objective and whether the run is out of date (is_stale — planning inputs… (leitura · — · transportadora · API: list_driver_schedules)
• lg driver-schedules reject — Dismiss ONE open schedule suggestion (suggestion_id from get_driver_schedule) so it is no longer offered; nothing is assigned or changed elsewhere. (escrita · — · transportadora · API: dismiss_driver_schedule_suggestion)
• lg driver-statements cancel — Cancel a statement that should not exist (opened by mistake, duplicated). (escrita · confirmação + irreversível · embarcador, transportadora · API: cancel_driver_account)
• lg driver-statements create — Open a NEW draft settlement statement for a driver. (escrita · confirmação · embarcador, transportadora · API: create_driver_account)
• lg driver-statements download — Give a short-lived download link to the PDF statement of a FINALISED driver settlement statement — the document the driver sees and signs, with every line, the fuel-card block that is outside the driver maths, and the… (leitura · — · embarcador, transportadora · API: download_driver_account_pdf)
• lg driver-statements finalize — FINALISE a draft settlement statement — it freezes the document, makes it visible to the driver and (for settle_cash) writes the counter-entry into the advance ledger. (escrita · confirmação + irreversível · embarcador, transportadora · API: finalize_driver_account) [chave manager]
• lg driver-statements get — Read one driver settlement statement in full: its status and revision, the driver, the currency, every total (expenses, advances, repayments, receiptless declarations), the NET balance with the sentence that says which… (leitura · — · embarcador, transportadora · API: get_driver_account)
• lg driver-statements list — List the driver settlement statements (mutabakat belgesi) of this company: code, which driver, status (draft / finalized / cancelled), currency, the net balance and what it means, how many expense and advance lines it… (leitura · — · embarcador, transportadora · API: list_driver_accounts)
• lg driver-statements reopen — Reopen a FINALISED statement so it can be corrected (a late receipt arrived, a line was wrong). (escrita · confirmação · embarcador, transportadora · API: reopen_driver_account) [chave manager]
• lg driver-statements update — Change the note printed on a DRAFT driver settlement statement (e.g. "September trips, fuel excluded"). (escrita · confirmação · embarcador, transportadora · API: update_driver_account)
• lg driver-statements update-lines — Attach receipts/advances to a DRAFT statement, or detach ones that should not be on it. (escrita · confirmação · embarcador, transportadora · API: update_driver_account_lines)
• lg driver-statuses list — Fleet command centre — every driver's live operational status in one list: last position and its AGE, signal health (streaming / delayed / stale / no_signal / permission_denied / app_missing), duty (on_trip / assigned /… (leitura · — · embarcador, transportadora · API: list_fleet_driver_statuses)
• lg drivers add-document — Record a driver paper — visa, passport, residence permit, driving licence, SRC certificate, psychotechnic certificate, travel health insurance — for ONE of this carrier's drivers, so its expiry is tracked. (escrita · confirmação · transportadora · API: add_driver_document) [recebe um arquivo: attachment_uuid]
• lg drivers archive — Archive (deactivate) a driver: their account is disabled, open mobile sessions are revoked and the login link stops working. (escrita · confirmação + irreversível · transportadora · API: archive_driver)
• lg drivers calculate — Check whether ONE driver can take a job: Schengen 90/180 days left at the end of the trip (expected and worst case, counting the drive back out and the driver's later planned work), leave / home-rest / sick periods,… (leitura · — · transportadora · API: check_driver_for_trip)
• lg drivers create — Create a new driver account for this carrier company. (escrita · confirmação · transportadora · API: create_driver)
• lg drivers delete-document — Remove a driver paper from the driver's file. (escrita · confirmação + irreversível · transportadora · API: delete_driver_document)
• lg drivers get — Full detail of ONE driver of this carrier: identity, archive state, mobile app state, last GPS position, assigned load codes, ALL driver documents (passport, visa, licence, SRC… with expiry and days_to_expiry) and the… (leitura · — · transportadora · API: get_driver)
• lg drivers list — List this carrier company's drivers with their status, current country, expiring/expired document counts, assigned load codes and vehicle plates. (leitura · — · transportadora · API: list_drivers)
• lg drivers list-candidates — Rank the company's drivers for a job — which drivers are available and can do it (Schengen days at trip end incl. the drive back, leave/home-rest, other jobs, estimated driving/rest readiness, distance to the start)… (leitura · — · transportadora · API: list_trip_driver_candidates)
• lg drivers list-documents — List ONE driver's documents (passport, visa, residence permit, licence, SRC, ADR, health insurance…) with document number, issuing country, valid_until, days_to_expiry, is_expired and AI extraction status. (leitura · — · transportadora · API: list_driver_documents)
• lg drivers list-locations — A driver's GPS trail — the raw position pings from the driver app in a time window, oldest to newest, with the first and last timestamps and the point count. (leitura · — · transportadora · API: list_driver_locations)
• lg drivers login-link — Produce the driver's 48-hour mobile app login link (sensitive credential). (escrita · confirmação · transportadora · API: get_driver_login_link)
• lg drivers request-location — Ask a driver's phone for a fresh position ("where is Ahmet right now — ping him"). (escrita · — · transportadora · API: request_driver_location)
• lg drivers search — Resolve one of this company's drivers by name to its driver_id. (leitura · — · transportadora · API: lookup_driver)
• lg drivers update — Correct a driver's first/last name. (escrita · confirmação · transportadora · API: update_driver)
• lg drivers update-document — Correct a driver paper already on file — most often its expiry date (valid_until) after a renewal, but also the document number, the issuing country, the type or the note. (escrita · confirmação · transportadora · API: update_driver_document)
• lg drivers update-login-link — Generate a NEW 48-hour mobile login link for a driver and kill the old one (lost phone, expired or leaked link). (escrita · confirmação + irreversível · transportadora · API: refresh_driver_login_link)
• lg equipment-damages create — Open a damage record on one of the company's own vehicles or trailers (dorse hasar kaydı aç) — "33ABC12 dorsesinin sol arka kapısında ezik var", "record a scratch on the rear bumper of the truck". (escrita · confirmação · todos · API: create_equipment_damage)
• lg equipment-damages delete — Delete a damage record that was opened by mistake (a duplicate, the wrong vehicle). (escrita · confirmação + irreversível · todos · API: delete_equipment_damage)
• lg equipment-damages generate — Produce the equipment damage ledger as an Excel file (the same file as the panel's export button) and return a short-lived download link — e.g. "give me this year's open trailer damages as Excel". (leitura · — · todos · API: export_equipment_damages)
• lg equipment-damages list — List the equipment/trailer damages recorded for this company: which vehicle, where on it (area and angle), damage type and severity, whether it is still open or repaired, the estimated and actual repair cost, who is… (leitura · — · todos · API: list_equipment_damages)
• lg equipment-damages update — Update an existing damage record: mark it repaired (with repair date, cost and note), dismissed or disputed, change severity/type/area/description, set the estimated cost, or set/clear the responsible driver. (escrita · confirmação · todos · API: update_equipment_damage)
• lg equipment-inspection-links create — Create a one-time link so a driver or agent who is NOT on the platform (port agent, another company's driver) can upload the hand-over photos of one of the company's trailers/vehicles from a phone, without an account. (escrita · confirmação · todos · API: create_equipment_inspection_link)
• lg equipment-inspections create — Record an equipment hand-over inspection of one of the company's own trailers or vehicles on behalf of a driver or the office — "record the pickup inspection of trailer 34ABC12 with these 4 photos, driver Ali".… (escrita · confirmação · todos · API: create_equipment_inspection) [recebe um arquivo: photos[].attachment_uuid]
• lg equipment-inspections delete — Delete an equipment inspection that was recorded by mistake (wrong vehicle, duplicate), together with its photos. (escrita · confirmação + irreversível · todos · API: delete_equipment_inspection)
• lg equipment-inspections get — Full detail of ONE equipment hand-over inspection: vehicle, event (pickup / dropoff / interim), who did it and where and when, the AI analysis status with its overall condition and summary, the damages that inspection… (leitura · — · todos · API: get_equipment_inspection)
• lg equipment-inspections list — List the equipment hand-over inspections (teslim-tesellüm controls) of this company: which vehicle, the event type (hand-over, take-over, interim), when and where it happened, who performed it (driver or office user, or… (leitura · — · todos · API: list_equipment_inspections)
• lg equipment-inspections run — Run the AI damage analysis again on the photos of one equipment inspection (for example after the analysis failed, or photos were added later). (escrita · confirmação · todos · API: reanalyze_equipment_inspection)
• lg equipment-settings get — Read the company's equipment inspection settings: whether the module is on, at which hand-overs an inspection is required (pickup / dropoff), whether photos are required, the minimum photo count, which angles are… (leitura · — · todos · API: get_equipment_settings)
• lg equipment-settings update — Change the company's equipment inspection settings — e.g. "turn on equipment inspection and require at least 4 photos with front, rear, left and right at pickup". (escrita · confirmação · todos · API: update_equipment_settings) [chave manager]
• lg equipment-timelines get — Who has one trailer/vehicle right now (custody: in custody of a driver since the last pickup, or released at the last dropoff), the inspections it went through (newest first) and its OPEN damages — in one read. (leitura · — · todos · API: get_equipment_timeline)
• lg export-documents add-item — Append a line item to an export document. (escrita · — · todos · API: add_export_document_item)
• lg export-documents create — Create a new export document draft. (escrita · — · todos · API: create_export_document_draft)
• lg export-documents create-set — Create SEVERAL export document drafts (a set, e.g. commercial invoice + packing list) from ONE source in one go: the source is read once by AI and every chosen document is filled from it. (escrita · — · todos · API: create_export_document_set) [recebe um arquivo: attachment_uuid]
• lg export-documents delete — Delete one export document of this company (draft or generated). (escrita · confirmação + irreversível · todos · API: delete_export_document)
• lg export-documents duplicate — Copy an existing export document into a NEW draft of the same type (same parties, items and terms; no document number, not generated). (escrita · — · todos · API: duplicate_export_document)
• lg export-documents extract — Read a pasted order e-mail, offer or confirmation — or an Excel/CSV/TXT item list given as attachment_uuid — and fill an export document from it. (escrita · — · todos · API: extract_export_document_from_text) [recebe um arquivo: attachment_uuid]
• lg export-documents generate — Produce the final PDF of an export document AND return a short-lived signed download link for it, so the user gets the file straight from the chat. (escrita · confirmação + irreversível · todos · API: generate_export_document)
• lg export-documents generate-set — Generate several export documents as PDFs in one go and return a short-lived download link for each generated one. (escrita · confirmação + irreversível · todos · API: generate_export_document_set)
• lg export-documents get — Read one export document in full: every filled field as dot-paths, the line items with their 1-based positions, the server-computed totals and which required fields are still empty. (leitura · — · todos · API: get_export_document)
• lg export-documents list — List the export documents of the current company (proforma invoice, commercial invoice, packing list, shipping instruction, delivery note, certificate/movement applications, exporter declaration, insurance request). (leitura · — · todos · API: list_export_documents)
• lg export-documents options — List the export document types and the ready-made document sets with their credit cost. (leitura · — · todos · API: get_export_document_options)
• lg export-documents preview — Before generating several export documents as PDFs, show what it would cost: which documents would spend a credit, which are free (already generated), the total, the remaining balance and the required fields still empty… (leitura · — · todos · API: plan_export_document_generation)
• lg export-documents remove-item — Delete one line item by its 1-based position. (escrita · — · todos · API: remove_export_document_item)
• lg export-documents set — Set one or more fields on an export document draft. (escrita · — · todos · API: set_export_document_fields)
• lg export-documents update-item — Change columns of one existing line item, addressed by its 1-based position from get_export_document. (escrita · — · todos · API: update_export_document_item)
• lg finance calculate — Build a budget / financial forecast (bütçe tahmini, gelecek yıl bütçesi, nakit/ciro projeksiyonu) from the company's MEASURED history, month by month. (leitura · — · todos · API: generate_budget_forecast)
• lg finance get — One call that returns the measured financial BASE for a period — the numbers a budget, a forecast, a business plan, a cash-flow projection or a board summary is built on, instead of chaining six separate reads. (leitura · — · todos · API: get_financial_snapshot)
• lg fleet-documents list — List fleet documents that expire soon (or already expired): vehicle papers (insurance, inspection, permits) and — for carriers — driver papers (passport, visa, licence, SRC). (leitura · — · embarcador, transportadora · API: list_expiring_documents)
• lg freight-invoices archive — Archive (remove from the active list) a freight invoice YOUR company uploaded — e.g. a duplicate or the wrong file. (escrita · confirmação + irreversível · todos · API: archive_freight_invoice)
• lg freight-invoices create — Attach 1-20 freight invoices (navlun faturası) to a load. (escrita · confirmação · todos · API: upload_freight_invoices) [recebe um arquivo: attachment_uuids]
• lg freight-invoices list — List the freight invoices (navlun faturaları) of a load that your company is a party to: who uploaded it, amount and currency, invoice date, the AI reading status, and which load parties it is shared with. (leitura · — · todos · API: list_freight_invoices)
• lg freight-invoices set-visibility — Choose which load parties can see a freight invoice YOUR company uploaded — e.g. "share the invoice with the receiver too", "only we should see it". (escrita · confirmação · todos · API: set_freight_invoice_visibility)
• lg freight-reports get — Freight (navlun) cost report over the loads this company can see: agreed freight totals per currency plus the EUR equivalent, freight-invoice totals, how many loads have NO freight recorded (listed by code), a breakdown… (leitura · — · embarcador, transportadora · API: get_freight_cost_report)
• lg fuel-cards create — Register a fuel card (DKV, UTA and the like) in the fleet card book, optionally tied to a driver or a vehicle. (escrita · confirmação · embarcador, transportadora · API: create_fuel_card)
• lg fuel-cards delete — Delete a fuel / toll card (DKV, UTA, Shell…) that was entered BY MISTAKE. (escrita · confirmação + irreversível · embarcador, transportadora · API: delete_fuel_card)
• lg fuel-cards list — List the company's fuel and toll cards (DKV, UTA, Eurowag, E100, Shell, OMV, Aral, Petrol Ofisi, Opet…) with the last four digits, the driver or vehicle they are tied to, and whether they are active. (leitura · — · embarcador, transportadora · API: list_fuel_cards)
• lg fuel-cards update — Update a fuel card: move it to another driver or vehicle, change its label or note, or DEACTIVATE it (is_active false) when the card is cancelled. (escrita · confirmação · embarcador, transportadora · API: update_fuel_card)
• lg handoff-links generate — Get the logistivo.com link for work that deliberately stays in the browser: package_purchase (buy or upgrade a package; optional package_slug from list_packages and billing_period monthly|yearly pre-select it — the… (leitura · — · todos · API: get_browser_handoff_link)
• lg import-duties get — Read the Turkish import duty table for one GTİP code: customs duty (İthalat Rejimi Kararı) and additional customs duty / İGV, with every country-group column, plus the statutory duty from the nomenclature. (leitura · — · todos · API: get_import_duty_rates)
• lg integration-keys list — List the company's integration (API) keys: name, uuid, which teammate it acts as, scope (read/write) and allowed domains, access level (manager/employee), environment (live/sandbox), status (active/revoked/expired),… (leitura · — · todos · API: list_integration_keys) [chave manager]
• lg integration-keys revoke — Revoke one of the company's integration (API) keys by its uuid from list_integration_keys: the key stops working immediately and cannot be re-enabled (issue a new key instead). (escrita · confirmação + irreversível · todos · API: revoke_integration_key) [chave manager]
• lg invitations create — Invite colleagues to this company by e-mail — one address in email, or up to 20 at once in emails (all-or-nothing: the seat limit and every address's domain are checked before anything is sent). (escrita · confirmação + irreversível · todos · API: invite_teammate) [chave manager]
• lg invitations list — List teammate invitations of this company that are not completed yet (pending / e-mail verified / account created), with invitation_code, e-mail, role and expiry. (leitura · — · todos · API: list_pending_invitations)
• lg invitations resend — Re-send a pending teammate invitation e-mail and extend its expiry by 14 days. (escrita · confirmação + irreversível · todos · API: resend_invitation) [chave manager]
• lg invitations revoke — Cancel a pending teammate invitation so its link stops working (it can later be re-sent). (escrita · confirmação · todos · API: revoke_invitation) [chave manager]
• lg invoice-settings get — Read the invoice document settings (fatura ayarları, fatura şablonu ayarları): which invoice templates exist, which template configuration is the company default, which fields of it are filled (logo, seller address,… (leitura · — · todos · API: get_invoice_settings)
• lg invoice-templates create — Create a new invoice template configuration for your company: a base template plus field values (colours, font, header / footer text, IBANs shown, QR code, language; logo and signature from uploaded images). (escrita · confirmação + irreversível · todos · API: create_invoice_template) [chave manager] [recebe um arquivo: logo_attachment_uuid, signature_image_attachment_uuid]
• lg invoice-templates delete — Delete one of your invoice template configurations. (escrita · confirmação + irreversível · todos · API: delete_invoice_template) [chave manager]
• lg invoice-templates get — Show the fillable fields of an invoice template (logo, colours, font, header / footer text, IBANs shown, QR code, signature, language) with their types, options and defaults — and, for one of your configurations, its… (leitura · — · todos · API: get_invoice_template)
• lg invoice-templates set-default — Make one of your invoice template configurations the company default; the previous default stops being default. (escrita · confirmação · todos · API: set_default_invoice_template) [chave manager]
• lg invoice-templates update — Edit one of your invoice template configurations: switch its base template, rename it, change field values (merged over the stored ones — only the keys you pass change), replace the logo / signature image, or make it… (escrita · confirmação + irreversível · todos · API: update_invoice_template) [chave manager] [recebe um arquivo: logo_attachment_uuid, signature_image_attachment_uuid]
• lg invoices add-line — Add a line item to a DRAFT invoice and recompute totals (tax auto-resolved if tax_rate_id omitted). (escrita · — · todos · API: add_invoice_line)
• lg invoices add-payment — Record money received (sales invoice) or paid (purchase invoice) against ONE issued invoice: writes the payment, posts the balanced journal entry and reduces the remaining balance. (escrita · confirmação + irreversível · todos · API: record_invoice_payment)
• lg invoices cancel — Cancel an ISSUED invoice this company issued: posts the reversing journal entry and marks the invoice cancelled. (escrita · confirmação + irreversível · todos · API: cancel_invoice)
• lg invoices create — Create a DRAFT invoice (reversible) issued by the current company to a recipient business contact. (escrita · — · todos · API: create_invoice_draft)
• lg invoices delete-draft — Delete a DRAFT invoice of this company together with its lines and taxes. (escrita · confirmação + irreversível · todos · API: delete_invoice_draft)
• lg invoices download — Get a short-lived download link for the PDF of an invoice visible to this company (and the e-invoice XML when one exists). (leitura · — · todos · API: download_invoice_pdf)
• lg invoices get — Read one invoice in full: parties, load link, dates, every line with tax, tax breakdown, totals, remaining balance and the payments recorded against it. (leitura · — · todos · API: get_invoice)
• lg invoices issue — Issue (finalize) a DRAFT invoice: assigns a number and posts accounting entries. (escrita · confirmação + irreversível · todos · API: issue_invoice)
• lg invoices list — List invoices visible to this company — the ones it issued and the ones issued to it (as a linked party). (leitura · — · todos · API: list_invoices)
• lg invoices preview — Show the user a full preview of a DRAFT invoice (recipient, line items, tax breakdown, totals) WITHOUT issuing it. (leitura · — · todos · API: preview_invoice · descontinuado: 2026-09-03 · use get_invoice)
• lg invoices remove-line — Remove one line from a DRAFT invoice your company issued; the totals are recalculated. (escrita · confirmação · todos · API: remove_invoice_line)
• lg invoices reverse-payment — Undo ONE payment/collection recorded on an invoice: posts the reversing journal entry, gives the amount back to the invoice's remaining balance and removes the payment row. (escrita · confirmação + irreversível · todos · API: reverse_invoice_payment)
• lg invoices update — Edit the header of a DRAFT invoice your company issued: recipient contact, currency, issue / due date, the printed note and the invoice template. (escrita · — · todos · API: update_invoice_draft)
• lg invoices update-line — Edit one line of a DRAFT invoice your company issued (text, quantity, unit, net unit price, discount, tax rate, order). (escrita · — · todos · API: update_invoice_line)
• lg join-requests approve — Approve a pending join request: the applicant becomes a user of our company with the EMPLOYEE role, takes one team seat and is e-mailed the decision. (escrita · confirmação + irreversível · todos · API: approve_join_request) [chave manager]
• lg join-requests list — List PENDING requests from people asking to join our company (they signed up with an e-mail on one of our verified domains and picked our company). (leitura · — · todos · API: list_join_requests) [chave manager]
• lg join-requests reject — Reject a pending join request: the applicant does not join our company and is e-mailed the decision. (escrita · confirmação + irreversível · todos · API: reject_join_request) [chave manager]
• lg journal-entries create — Post a manual double-entry journal entry (yevmiye fişi). (escrita · confirmação + irreversível · todos · API: create_journal_entry)
• lg journal-entries get — Read one journal entry with its lines (account code/name, debit, credit, counterparty) and totals. (leitura · — · todos · API: get_journal_entry)
• lg journal-entries list — List journal entries (yevmiye fişleri) of the company, newest first, with optional date window. (leitura · — · todos · API: list_journal_entries)
• lg language-settings get — Read the signed-in user's own language settings (dil ayarları). (leitura · — · todos · API: get_language_settings)
• lg language-settings update — Change the signed-in user's OWN language settings — "dilimi İngilizce yap", "e-postalarım Türkçe gelsin", "sohbet mesajlarını Almancaya çevir". (escrita · — · todos · API: set_language)
• lg load-ai-settings get — Read our company's load AI reminder setting (Settings → Loads): whether the assistant posts reminders into load chats about loads whose status was not updated (ai_warning_enabled) and on which days (warning_frequency:… (leitura · — · todos · API: get_load_ai_settings)
• lg load-ai-settings update — Change our company's load AI reminders (Settings → Loads): ai_warning_enabled turns the reminders the assistant posts into load chats on or off; warning_frequency picks the days (daily, mon_wed_fri, weekly_wed,… (escrita · confirmação · todos · API: update_load_ai_settings) [chave manager]
• lg load-containers create — Add a sea container number to a load (yüke konteyner ekle) — "add MSC container MSCU1234565 to FKZ8515". (escrita · confirmação · embarcador, transportadora · API: add_load_container)
• lg load-containers delete — Delete a container record from a load (konteyneri sil) — only while its vessel tracking has NOT started (otherwise refused with INVALID_STATUS). (escrita · confirmação + irreversível · todos · API: delete_load_container)
• lg load-containers get — Show one container of a load and the last known position of the ship carrying it (konteyner konumu): ship name/IMO, latitude/longitude, speed, course, destination, ETA and the position time. (leitura · — · todos · API: get_load_container)
• lg load-containers list — List the sea containers recorded on a load (konteynerler) with their shipping line, whether vessel tracking has started and which ship carries them. (leitura · — · todos · API: list_load_containers)
• lg load-containers set-tracking — Start vessel tracking for a load from its containers (konteyner takibini başlat): the shipping line is queried for each container until the vessel carrying it is found; that ship is then tracked on the load's map and… (escrita · confirmação · todos · API: start_load_container_tracking)
• lg load-documents create — File one or MANY documents the user attached to this conversation onto a load: each file is stored as a company document and posted into the load's chat, where every participant (customer, carrier, customs broker) sees… (escrita · confirmação + irreversível · todos · API: attach_chat_file_to_load) [recebe um arquivo: attachment_uuid, attachment_uuids]
• lg load-documents list — List the documents (CMR, invoice, packing list, customs papers, photos…) filed on a load — i.e. the files shared in that load's chat. (leitura · — · todos · API: list_load_documents)
• lg load-groups add-loads — Merge EXISTING loads into a groupage trip you own as consignments (they keep their own code, chat, documents and participants; only the trip membership changes — nothing is duplicated and NO credit is used). (escrita · confirmação · embarcador, transportadora · API: add_loads_to_group)
• lg load-groups create — Create a groupage trip (parsiyel/sefer): ONE truck carrying several ISOLATED consignments; each consignment is its own load with its own chat/documents/status and receivers never see each other. (escrita · confirmação + irreversível · embarcador, transportadora · API: create_load_group)
• lg load-groups download — Download the route report of a groupage trip (sefer / parsiyel, code like LGV00253): route_pdf = detailed route report with map and itinerary, route_xlsx = the same as Excel, driver_sheet_pdf = the simplified driver… (escrita · — · embarcador, transportadora · API: download_load_group_report)
• lg load-groups get — Detail of one groupage trip: consignments visible to you (load code, status, receiver, route, driver), planned date, optimised master route summary and stop count. (leitura · — · embarcador, transportadora · API: get_load_group)
• lg load-groups list — List groupage trips (parsiyel / sefer: one truck, several isolated consignment loads) this company owns or — for carriers — carries, newest first, with visible consignment count and route optimisation state. (leitura · — · embarcador, transportadora · API: list_load_groups)
• lg load-groups optimize — Re-optimise the master route of a groupage trip you own and RETURN the new itinerary: the ordered stops (pickup → export customs → import customs → dropoff), each stop's address and consignment codes, the total distance… (escrita · — · embarcador, transportadora · API: optimize_trip_route)
• lg load-groups remove-load — Take one consignment out of a groupage trip you own. (escrita · confirmação · embarcador, transportadora · API: remove_load_from_group)
• lg load-heatmaps generate — Produce the load heatmap report (PDF, with QR code and the list of your active loads: code, departure, arrival, date, weight), save it to the company's reports and return a download link. (escrita · confirmação + irreversível · todos · API: generate_load_heatmap_report)
• lg load-heatmaps get — Load heatmap data in words: the densest departure and arrival areas of your active loads, ranked by number of loads and by total kilograms. (leitura · — · todos · API: get_load_heatmap)
• lg load-locations create — Report a position for a load on behalf of the carrier (konum bildir) — "FKZ8515 is at Kapıkule now", "the truck is at 41.0, 28.9". (escrita · confirmação + irreversível · transportadora · API: report_load_location)
• lg load-locations list — Show a load's position history (konum geçmişi) and its last known position — "where is FKZ8515 now", "where was it yesterday", "show the truck's track". (leitura · — · todos · API: list_load_locations)
• lg load-locations list-routes — Show the road route segments drawn on a load's tracking map (rota parçaları), each with distance (metres) and duration (seconds): from the pickup address to the first reported position, between reported positions, and… (leitura · — · todos · API: list_load_route_segments)
• lg load-notifications list-recipients — Show which load parties can receive a load notification (departure, arrival, daily location) and how many of their people are subscribed per channel (e-mail, push, SMS). (leitura · — · todos · API: list_load_notification_recipients)
• lg load-notifications send — Send a departure / arrival / daily-location notification about a load to chosen load parties — e.g. "notify the receiver that FRT6470 arrived". (escrita · confirmação + irreversível · todos · API: send_load_notification)
• lg load-notifications send-email — E-mail a departure / arrival / location update about a load to people you choose from YOUR OWN company directory (business contact persons) — e.g. "e-mail Mehmet at Arkas the location of FKZ8515". (escrita · confirmação + irreversível · todos · API: send_load_email_notification)
• lg load-participants create — Add a party to a load (yüke taraf ekle) — "FKZ8515'e Arkas'ı alıcı olarak ekle" — or assign a sub-carrier. business_contact_id comes from lookup_business_contact (your own directory). (escrita · confirmação · todos · API: add_load_participant)
• lg load-participants delete — Remove a party or a sub-carrier from a load (yükten taraf çıkar) — "FKZ8515'ten alt taşıyıcı Yılmaz Nakliyat'ı kaldır". participant_id comes from list_load_participants. (escrita · confirmação · todos · API: remove_load_participant)
• lg load-participants list — List a load's parties (yük tarafları): sender, receiver, carrier and sub-carriers, organizer, sender/receiver customs brokers — with participant_id (needed by every other load-participant command), position (0 = primary… (leitura · — · todos · API: list_load_participants)
• lg load-participants set-order — Put the parties of one role in a new order (load owner only); the first id becomes the primary. participant_ids must list ALL current rows of that role (from list_load_participants). (escrita · confirmação · todos · API: reorder_load_participants)
• lg load-participants set-primary — Make a party the primary one in its role (load owner only) — e.g. the main receiver or main customs broker. participant_id from list_load_participants. (escrita · confirmação · todos · API: set_primary_load_participant)
• lg load-participants update — Change one load party's settings (load owner only) — "Arkas FKZ8515'i görmesin": share_with_assigned_company (can the linked company see the load; cannot be turned off for a sub-carrier), conversation_user_ids (only… (escrita · confirmação · todos · API: update_load_participant)
• lg load-party-suggestions approve — Accept a party suggestion: link the suggested business contact to your OWN load as sender or receiver (business_contact_id and party_role from list_load_party_suggestions). (escrita · confirmação · todos · API: confirm_load_party_suggestion)
• lg load-party-suggestions list — Show sender/receiver suggestions for one of your OWN loads: parties named in the load's documents that match a contact in your directory but are not linked to the load yet. (leitura · — · todos · API: list_load_party_suggestions)
• lg load-party-suggestions reject — Close wrong party suggestions on your OWN load so they are not suggested again — "bu önerileri bir daha gösterme". (escrita · — · todos · API: dismiss_load_party_suggestions)
• lg load-reports get — Build a report of your ACTIVE loads, optionally filtered by sender, receiver, transport mode, departure country or arrival country. format=summary (default) answers in chat: the number of loads and how many are in each… (leitura · — · todos · API: get_load_report)
• lg load-reports options — List the companies you can filter the load report by — the senders, receivers, carriers and other parties that appear on your active loads — with their company id and role. (leitura · — · todos · API: get_load_report_options)
• lg load-types search — Resolve a load/transport type (e.g. (leitura · — · todos · API: lookup_load_type)
• lg load-vehicles delete — Detach the fleet equipment from a load: both slots by default, or only the tractor unit / only the trailer. (escrita · confirmação · todos · API: clear_load_equipment)
• lg load-vehicles get — Show which tractor unit (or truck/van) and which trailer are attached to a load, whether they belong to your own fleet, and whether the load can still be changed. (leitura · — · todos · API: get_load_equipment)
• lg load-vehicles set — Attach one of your own fleet vehicles to a load: the tractor unit / truck slot (plate) and/or the trailer slot (trailer_plate). (escrita · confirmação · todos · API: assign_vehicle_to_load)
• lg loads add-order-reference — Attach an order reference to a load (sipariş referansı ekle) — "FKZ8515'e satın alma siparişi PO-4471 ekle". order_type is the kind of order (e.g. purchase, sales), order_no the number. (escrita · confirmação + irreversível · todos · API: add_load_order_reference)
• lg loads analyze-documents — Re-run the background AI consistency analysis of a load's documents (does the invoice contradict the CMR, the packing list, the declared weight…) and refresh the load's problem flag with the outcome. (escrita · — · todos · API: reanalyze_load_documents)
• lg loads archive — Archive one of the company's OWN loads (yükü arşivle) — "FKZ8515'i arşive al". (escrita · confirmação + irreversível · todos · API: archive_load)
• lg loads assign-driver — Assign one of this company's drivers to a load so the driver sees it in the mobile app and starts reporting position. (escrita · confirmação · transportadora · API: assign_driver_to_load)
• lg loads audit-documents — Cross-check the documents already attached to loads and report, PER LOAD, whether their package counts and gross weights agree. (leitura · — · todos · API: audit_load_documents)
• lg loads close-problem — Close the open document-consistency flag of ONE load, from the chat. action=resolved means the contradiction was actually fixed (a corrected document was uploaded); action=dismissed means it was a false alarm and should… (escrita · confirmação · todos · API: resolve_load_problem_flag)
• lg loads create — Open a freight load (yük). (escrita · confirmação + irreversível · todos · API: create_load)
• lg loads download — Generate a load's CMR consignment note as a PDF and return a short-lived download link — "FKZ8515'in CMR'ını ver". (leitura · — · todos · API: download_load_cmr)
• lg loads extract — Read a booking/order text (an e-mail body, a note, an ERP export line) and return the load fields it contains, in the quick-load form's shape: transport mode, countries, dates, load type, vehicle type, weight, goods… (leitura · — · embarcador · API: extract_load_from_text)
• lg loads get — Read one load in full by its code: route, dates, weight, current status, parties (sender/receiver/carrier), agreed freight (freight_amount + freight_currency) with its freight invoices (number, date, total), latest… (leitura · — · todos · API: get_load)
• lg loads list — List the freight loads (yük) this company can see, newest first. (leitura · — · todos · API: list_loads)
• lg loads list-associated — List the loads of the same multi-vehicle order as a given load (aynı siparişin diğer araçları) — every active load that shares its vehicle group code (LG…) and that your company can see, with status, date and carrier. (leitura · — · todos · API: list_associated_loads)
• lg loads list-billing-targets — Show who you can invoice for a load: its commercial parties (sender, receiver, carrier) you are allowed to bill, each with recipient_contact_id to pass to create_invoice_draft and in_my_directory (true = already in your… (leitura · — · todos · API: list_load_billing_targets)
• lg loads list-problems — List loads whose uploaded documents the AI consistency check found to CONTRADICT each other (e.g. invoice weight vs CMR weight). (leitura · — · todos · API: list_load_problem_flags)
• lg loads list-status-history — Show a load's status history (durum geçmişi) in order — when it went pending, in transport, transit, delivered (done). (leitura · — · todos · API: list_load_status_history)
• lg loads list-stops — List the stops of a multi-stop load (çok duraklı yük — several pickups/drop-offs on one load) in route order, with type (pickup, dropoff, customs_exit, customs_entry), company, address, leg distance/duration and whether… (leitura · — · todos · API: list_load_stops)
• lg loads optimize — Re-order the stops of a multi-stop load for the shortest driving route (pickups first, then drop-offs) and store the new order with leg distances — "optimise FKZ8515's stops". (escrita · — · todos · API: optimize_load_stops)
• lg loads options — Read a load's editable fields, their current values and the allowed options (load types, vehicle types, goods classes, stackability, incoterms, movement types) — "FKZ8515'te neyi değiştirebilirim?". (leitura · — · todos · API: get_load_edit_form)
• lg loads preview-copy — Prepare a copy draft of one of your company's OWN loads (yükü kopyala) — "FKZ8515'in aynısından bir tane daha açalım": transport mode, countries, addresses, load type, vehicle type, weight, goods class, incoterms, ports… (leitura · — · todos · API: get_load_copy_template)
• lg loads remove-driver — Remove the driver from a load (the opposite of assign_driver_to_load): the load disappears from the driver's app and GPS tracking of the load stops. (escrita · confirmação · transportadora · API: unassign_driver_from_load)
• lg loads search — Full-text search across your loads (yük ara) — company names, pickup/delivery address, order references, load code, text written in the load chat and text read from documents shared in the chat: "içinde PO-4471 geçen… (leitura · — · todos · API: search_loads)
• lg loads set-status — Move a load to a new transport status and append it to the load's status history (this is what the customer sees on the tracking screen). (escrita · confirmação + irreversível · transportadora · API: update_load_status)
• lg loads set-stop-status — Mark one stop of a multi-stop load as completed, or undo it (completed=false) — "FKZ8515's second drop-off is done". (escrita · confirmação · transportadora · API: mark_load_stop_completed)
• lg loads set-tracking — Turn a load's GPS location tracking on or off (konum takibi) — "stop location tracking for FKZ8515", "resume tracking". (escrita · confirmação · transportadora · API: set_load_location_tracking)
• lg loads update — Edit an existing load (yükü düzenle): loading date, weight, load type, vehicle types, goods class, stackability, pickup/delivery address, incoterms, movement type, loading/destination port. (escrita · confirmação + irreversível · todos · API: update_load)
• lg maturity-options list — The selectable payment terms (vade): maturity_option_id and the number of days (0 = cash / peşin). maturity_option_id is what update_company_profile takes. (leitura · — · todos · API: list_maturity_options)
• lg notification-settings get — Read our company's notification switches (Settings → Notifications): which e-mail notifications (type "notification") and push notifications (type "web-push") are on for the whole company — e.g. message, load, demand… (leitura · — · embarcador · API: get_notification_settings) [chave manager]
• lg notification-settings update — Turn our company's notification switches on or off (Settings → Notifications) — e.g. stop load chat push notifications or message e-mails for the whole company. settings is a list of {slug, enabled}; slugs come from… (escrita · confirmação · embarcador · API: update_notification_settings) [chave manager]
• lg notifications list — Read the signed-in user's own notification inbox (the bell icon): what happened, which kind of event it was, when, whether it is still unread, and the panel address the notification points at. (leitura · — · todos · API: list_notifications)
• lg notifications mark-read — Mark ALL of the signed-in user's unread notifications as read (empty the bell). (escrita · — · todos · API: mark_notifications_read)
• lg packages get — Read this company's package and CREDIT balance: how many credits are left, how many the package grants per year, how many were used, the renewal date, and the assistant token usage of the current period (1,000,000… (leitura · — · todos · API: get_credit_balance)
• lg packages list — List the Logistivo packages this company can buy: slug, name, monthly price and yearly upfront total in the company's BILLING currency (TRY for Türkiye-billed companies, EUR otherwise — never converted with an exchange… (leitura · — · todos · API: list_packages)
• lg pallets add-measurement — Record a NEW measurement for an existing pallet (dimensions in centimetres and/or gross weight in kilograms). (escrita · confirmação · todos · API: add_pallet_measurement)
• lg pallets add-proof — Attach a proof photo to one of this company's pallets (e.g. the wrapped pallet, its label, damage on arrival). (escrita · — · todos · API: add_pallet_proof) [recebe um arquivo: attachment_uuid]
• lg pallets calculate — Suggest the missing base side of a pallet from a standard footprint (EUR 120×80, industrial 120×100, half 80×60; ±5 cm) when only one base side is known, and compute the volume when length, width and height are all… (leitura · — · todos · API: complete_pallet_dimensions)
• lg pallets create — Register a NEW pallet in a warehouse, optionally with its first measurement. warehouse_id is required — resolve the warehouse name with lookup_warehouse first. (escrita · confirmação · todos · API: create_pallet)
• lg pallets delete — Delete one of this company's pallet records. (escrita · confirmação + irreversível · todos · API: delete_pallet)
• lg pallets delete-proof — Remove one proof photo from one of this company's pallets. (escrita · confirmação + irreversível · todos · API: delete_pallet_proof)
• lg pallets extract — Estimate a pallet's content label, dimensions (cm) and gross weight (kg) from photo(s) the user attached to THIS conversation. (escrita · — · todos · API: extract_pallet_from_photos) [recebe um arquivo: attachment_uuids]
• lg pallets get — Read one pallet in full: its identity (code, label, SKU, barcode), status, warehouse and area, the FULL measurement history (each row with its id, source — manual, lidar, arcore or ai_photo — and confidence), its proof… (leitura · — · todos · API: get_pallet)
• lg pallets list — List the pallets of this company: code, label, SKU/barcode, status, which warehouse and area it sits in, its latest measured dimensions (cm) and gross weight, and how many proof photos it has. (leitura · — · todos · API: list_pallets)
• lg pallets update — Update an existing pallet: its status (in_stock, in_transit, reserved, shipped, disposed), its label/SKU/barcode/note, or MOVE it to another warehouse or area. (escrita · confirmação · todos · API: update_pallet)
• lg parasut-contacts create — Create a new customer or supplier contact IN PARAŞÜT and keep its local copy. (escrita · confirmação + irreversível · todos · API: create_parasut_contact)
• lg parasut-contacts list — List the customer / supplier contacts held in Paraşüt (the local copy synchronised from Paraşüt): parasut_contact_id (the Paraşüt id used by create_parasut_sales_invoice — NOT a business contact id), name, short name,… (leitura · — · todos · API: list_parasut_contacts)
• lg parasut-invoices create — Issue a SALES invoice in Paraşüt for one of this company's Paraşüt contacts, as an e-invoice (scenario commercial or basic — the recipient must be an e-invoice user) or an e-archive invoice (scenario e_archive); check… (escrita · confirmação + irreversível · todos · API: create_parasut_sales_invoice)
• lg parasut-invoices list — List invoices held in Paraşüt (local copy): sales invoices (default) or purchase bills, newest issue date first — invoice id and number, item type, description, issue / due date, net / gross / VAT totals, currency,… (leitura · — · todos · API: list_parasut_invoices)
• lg parasut-invoices options — Return the options of the Paraşüt invoice form: income/expense categories (category_id), the Paraşüt bank and cash accounts, and — with tax_number — whether that VKN is a registered e-invoice user (then use scenario… (leitura · — · todos · API: get_parasut_invoice_options)
• lg parasut-settings delete — Disconnect Paraşüt from this company: the saved credentials are removed, the accounting provider switches back to local when it was Paraşüt, and the LOCAL copies pulled from Paraşüt (contacts, invoices, bank accounts,… (escrita · confirmação + irreversível · todos · API: disconnect_parasut) [chave manager]
• lg parasut-settings get — Show the Paraşüt integration status of this company: whether it is connected, the Paraşüt firm number, the user name, the client id/secret MASKED (last 4 characters only), when it was connected, the token status and the… (leitura · — · todos · API: get_parasut_settings) [chave manager]
• lg parasut-settings update — Connect this company's Paraşüt account or renew its credentials (replaces an existing connection). (escrita · confirmação · todos · API: connect_parasut) [chave manager] [somente CLI]
• lg payables list — Payables ("whom do we owe how much"): per-supplier totals of recorded purchase invoices — invoiced, paid, remaining, earliest due date — with a per-currency breakdown and an overall summary. (leitura · — · todos · API: list_payables)
• lg payment-cards delete — Remove a saved payment card (card_id from list_payment_cards). (escrita · confirmação + irreversível · todos · API: delete_payment_card) [chave manager]
• lg payment-cards list — List the company's saved payment cards, MASKED (last four digits only), with the card holder name, expiry and which one is the default card the monthly subscription is charged to. (leitura · — · todos · API: list_payment_cards)
• lg payment-cards set-default — Make one of the saved cards (card_id from list_payment_cards) the DEFAULT card: the monthly package payment is charged to it from now on, and every other card loses the default flag. (escrita · confirmação + irreversível · todos · API: set_default_payment_card) [chave manager]
• lg payment-instructions cancel — CANCEL a pending bank payment instruction: the reservation on its invoices is released so they can be paid another way, and the instruction becomes "cancelled". (escrita · confirmação + irreversível · todos · API: cancel_settlement_instruction)
• lg payment-instructions download — Get the bank payment instruction document (PDF) with a short-lived download link. (leitura · — · todos · API: download_settlement_instruction)
• lg payment-instructions get — Read one bank payment instruction: its code, template, effective date, status with timestamps and cancel reason, its note, and — when the PDF has already been rendered — a short-lived signed link to it so the user gets… (leitura · — · todos · API: get_settlement_instruction)
• lg payment-instructions list — List the bank payment instructions of this company: instruction code, which template (bank format) it uses, its effective date, status (pending, executed, cancelled) and when it was executed or cancelled. (leitura · — · todos · API: list_settlement_instructions)
• lg payment-instructions run — EXECUTE a pending bank payment instruction (banka talimatını yürüt / uygula): the reserved invoices are paid, the payments and journal entries are written with the instruction's effective date, and the instruction… (escrita · confirmação + irreversível · todos · API: execute_settlement_instruction)
• lg planning-boards get — The planning calendar: for every driver, the stretches of days with planned work inside the Schengen area (planned_in), days assumed inside (drive back, assumed_in), planned work outside (planned_out), leave / rest… (leitura · — · transportadora · API: get_planning_board)
• lg plans archive — Close a plan because the user says the work is finished or abandoned. (escrita · — · todos · API: archive_plan)
• lg plans create — Write down a multi-step job so it survives between conversations ("link these 5 loads to a trip, then invoice them"). (escrita · confirmação · todos · API: create_plan)
• lg plans get — Read one plan: the steps that were agreed AND the commands that actually ran while it was active. (leitura · — · todos · API: get_plan)
• lg plans list — List this company's plans, newest first. (leitura · — · todos · API: list_plans)
• lg ports search — Find a seaport by name or UN/LOCODE (liman ara) — "Mersin", "TRMER", "Trieste". (leitura · — · todos · API: lookup_port)
• lg preferences create — Remember a lasting preference of THIS user, so it applies to every future conversation too ("always show amounts in EUR", "write driver names surname first", "I want the weekly summary on Mondays"). (escrita · — · todos · API: remember_preference)
• lg preferences delete — Forget one stored preference of this user. (escrita · — · todos · API: forget_preference)
• lg preferences list — List what you have been asked to remember about THIS user, with the labels. (leitura · — · todos · API: list_preferences)
• lg product-brands create — Create a new product brand for this company (the panel's "new brand"). (escrita · confirmação · embarcador · API: create_product_brand)
• lg product-brands list — List this company's product brands (id, name, code, active flag, number of products). (leitura · — · embarcador · API: list_product_brands)
• lg product-categories create — Create a new product category for this company (the panel's "new category"). (escrita · confirmação · embarcador · API: create_product_category)
• lg product-categories list — List this company's product categories (id, name, code, active flag, number of products). (leitura · — · embarcador · API: list_product_categories)
• lg products add-image — Add a photo to a product's gallery. (escrita · — · embarcador · API: add_product_image) [recebe um arquivo: attachment_uuid]
• lg products create — Define a new product in this company's catalogue so stock can be recorded against it: name plus optionally its unit of measure, SKU, barcode, category, brand, minimum stock level, reorder quantity and lot tracking. (escrita · confirmação · embarcador · API: create_product)
• lg products delete — Delete a product from this company's catalogue. (escrita · confirmação + irreversível · embarcador · API: delete_product)
• lg products delete-image — Remove one photo from a product's gallery (image_id from get_product). (escrita · confirmação + irreversível · embarcador · API: delete_product_image)
• lg products extract — Read product details (name, description, SKU, barcode, unit, category, brand) from 1-5 photos of the product or its label — the panel's "fill from photo" button. (escrita · — · embarcador · API: extract_product_from_photos) [recebe um arquivo: attachment_uuids]
• lg products get — Show one product of this company in full: code, SKU, barcode, unit, category and brand, low-stock threshold and reorder quantity, lot tracking, its photos (with image_id for delete_product_image /… (leitura · — · embarcador · API: get_product)
• lg products list — List the products of this company: code, name, SKU/barcode, unit, category and brand, whether it is active, and its low-stock threshold. (leitura · — · embarcador · API: list_products)
• lg products list-low-stock — List the products whose quantity on hand is BELOW their low-stock threshold (strictly below — a product exactly at the threshold is not listed), with the quantity on hand and the threshold itself. (leitura · — · embarcador · API: list_low_stock_products)
• lg products options — List the units of measure a product can be held in (slug for create_product / update_product unit, with Turkish and English names). (leitura · — · embarcador · API: get_product_options)
• lg products search — Resolve a product to its product_id + on-hand quantity. (leitura · — · embarcador · API: lookup_product)
• lg products set-primary-image — Make one of a product's photos its cover image (image_id from get_product). (escrita · — · embarcador · API: set_product_primary_image)
• lg products update — Correct an existing product: its name, unit, SKU, barcode, category, brand, minimum stock level, reorder quantity, lot tracking, note, or whether it is active. (escrita · confirmação · embarcador · API: update_product)
• lg receivables get — Account statement of one contact: every sales invoice issued to them and every collection, in date order with a running balance, plus totals (invoiced, paid, open balance, open invoice count). (leitura · — · todos · API: get_receivable_statement)
• lg receivables list — Receivables ("who owes us how much"): per-contact totals of issued sales invoices — invoiced, paid, remaining — with a per-currency breakdown and an overall summary. (leitura · — · todos · API: list_receivables)
• lg report-files create — Turn a table you compiled from tool results into a downloadable Excel (default), PDF or CSV file — any custom table, list, comparison or export, with optional charts. (leitura · — · todos · API: create_report_file)
• lg reports get — Financial reports from posted journal entries: trial_balance (per-account debit/credit/balance as of a date), balance_sheet (as of a date) or income_statement (revenues/expenses/net income for a date range; defaults to… (leitura · — · todos · API: get_accounting_report)
• lg reservations approve — As the warehouse owner, approve a pending reservation received at your warehouse (the booker is notified). (escrita · confirmação · embarcador · API: approve_reservation)
• lg reservations cancel — Cancel (withdraw) a warehouse reservation you booked, or — as the warehouse owner (customer) — cancel a reservation received at your warehouse. (escrita · confirmação + irreversível · todos · API: cancel_reservation)
• lg reservations complete — As the warehouse owner, mark an APPROVED reservation at one of your warehouses as completed (the vehicle came and the work is done). (escrita · confirmação + irreversível · embarcador · API: complete_reservation)
• lg reservations create — Book a warehouse dock time slot. (escrita · confirmação · todos · API: create_reservation)
• lg reservations get — Detail of one warehouse reservation you booked or (customer) one received at your warehouse: warehouse, area, time window, status, contact, notes, rejection reason. (leitura · — · todos · API: get_reservation)
• lg reservations list — List warehouse dock reservations. side=booked_by_me (default): reservations this user/company booked at other companies' warehouses. side=received (customer role only): reservations other companies made at ONE of your… (leitura · — · todos · API: list_reservations)
• lg reservations list-slots — Available dock time slots of one day with remaining capacity. (leitura · — · todos · API: list_reservation_slots)
• lg reservations reject — As the warehouse owner, reject a pending reservation received at your warehouse, with an optional reason shown to the booker. (escrita · confirmação + irreversível · embarcador · API: reject_reservation)
• lg reservations reschedule — As the warehouse owner, move a PENDING or APPROVED reservation at one of your warehouses to a new time. (escrita · confirmação · embarcador · API: reschedule_reservation)
• lg roro-routes list — For a load you are carrying, list the Ro-Ro (ferry) lines closest to its PICKUP address, nearest first: the line name, its departure and arrival ports and how many kilometres the pickup point is from the departure port. (leitura · — · transportadora · API: list_nearby_roro_routes)
• lg roro-routes select — Select the Ro-Ro (ferry) line a load you are carrying will use. (escrita · confirmação · transportadora · API: select_roro_route)
• lg roro-routes set-required — Mark whether a load you are carrying will travel by Ro-Ro (ferry) or not. (escrita · confirmação · transportadora · API: set_load_roro_required)
• lg route-plans assign-driver — Assign a driver (and, on a double-crew plan, a co-driver; optionally the vehicle/trailer) to a saved route plan (route_plan_id or route_plan_code). (escrita · confirmação · transportadora · API: assign_driver_to_route_plan)
• lg route-plans calculate — Calculate a multi-stop truck journey WITHOUT saving it: truck driving time (car time × hgv_factor, capped speed), the EU 561/2006 / AETR breaks, daily and weekly rests, weekend/holiday driving bans and border waits, and… (escrita · confirmação · transportadora · API: calculate_route_plan)
• lg route-plans create — Save a route plan as a DRAFT (same arguments as calculate_route_plan, plus name, vehicle_id, trailer_id, start_flex_days). (escrita · confirmação · transportadora · API: create_route_plan)
• lg route-plans delete — Cancel and delete a route plan (route_plan_id or route_plan_code). (escrita · confirmação + irreversível · transportadora · API: delete_route_plan)
• lg route-plans get — One saved route plan: stops with arrival/departure ranges, the summary (distance, truck driving time, arrival optimistic / expected / conservative, breaks, daily/weekly rests, reduced rests, border waits), Schengen days… (leitura · — · transportadora · API: get_route_plan)
• lg route-plans list — List the company's saved route plans, newest first: code, name, status (draft | assigned | converted | cancelled), departure, crew, driver, vehicle, linked load/trip, stops, arrival range and Schengen day count. (leitura · — · transportadora · API: list_route_plans)
• lg route-plans preview — Compare 1-6 variants of the same journey side by side — different drivers, departure days or a double crew: arrival range, driving and rest counts, Schengen days left at the end for every crew member, availability /… (escrita · confirmação · transportadora · API: compare_route_plan_scenarios)
• lg route-plans remove-driver — Take the driver (and co-driver) off an assigned route plan (route_plan_id or route_plan_code); the plan goes back to draft and stops counting as planned Schengen days for them. (escrita · confirmação · transportadora · API: unassign_driver_from_route_plan)
• lg route-plans select — Link a saved route plan (route_plan_id or route_plan_code) to the load or trip it was planned for — give load_code OR trip_code; give neither to remove the link. (escrita · confirmação · transportadora · API: link_route_plan)
• lg route-plans update — Change a saved route plan (route_plan_id or route_plan_code): any create_route_plan field — name, departure, stops, crew, options, vehicle. (escrita · confirmação · transportadora · API: update_route_plan)
• lg schengen-stays calculate — Project ONE driver's Schengen 90/180 days into the future: days used today, then how the remaining days move with the loads, trips and route plans already assigned to him (plus the drive back out) and his leave /… (leitura · — · transportadora · API: get_driver_schengen_projection)
• lg schengen-stays create-set — Import drivers' past Schengen entry/exit periods (passport stamps) from an Excel/CSV file — one row per stay: driver code or name, entry date, exit date (empty = still inside). (escrita · confirmação · transportadora · API: import_driver_schengen_periods) [recebe um arquivo: attachment_uuid]
• lg schengen-stays download — Give a short-lived download link to the Schengen history import template, pre-filled with the company's active drivers (user code + name; entry/exit date cells empty). (leitura · — · transportadora · API: download_schengen_import_template)
• lg schengen-stays get — One driver's full Schengen 90/180 picture: days used (confirmed / declared / inferred), days left (signed; negative = overstay), latest exit date, breach date, when days come back (regain schedule), per-country day… (leitura · — · transportadora · API: get_driver_schengen_detail)
• lg schengen-stays list — Fleet-wide Schengen 90/180 compliance: which drivers breached the 90-days-in-180 rule or are close to it, how many days each has left (days_remaining is SIGNED — negative means overstay), the latest exit date… (leitura · — · transportadora · API: list_schengen_compliance)
• lg schengen-stays list-periods — List the Schengen stay periods DECLARED for a driver (passport stamps / starting balance) with their period_id, entry and exit dates and day count. (leitura · — · transportadora · API: list_driver_schengen_periods)
• lg schengen-stays remove-period — Delete ONE wrongly entered declared Schengen period of a driver (period_id from list_driver_schengen_periods). (escrita · confirmação + irreversível · transportadora · API: delete_driver_schengen_period)
• lg schengen-stays set-baseline — Set a driver's Schengen starting balance — what happened BEFORE GPS tracking: either the exact periods inside the zone from passport stamps (baseline_mode=periods) or just "X days used in the last 180"… (escrita · confirmação · transportadora · API: set_driver_schengen_baseline)
• lg schengen-stays set-exemption — Exempt a driver from Schengen 90/180 tracking (EU/EFTA passport, residence permit, national long-stay visa) or switch the rule back on. (escrita · confirmação · transportadora · API: set_driver_schengen_exemption)
• lg settlements cancel — CANCEL a bulk collection / payment (settlement batch). (escrita · confirmação + irreversível · todos · API: cancel_settlement_batch) [chave manager]
• lg settlements create — Close several open invoices of ONE contact in ONE currency in a single bulk collection (direction in) or bulk payment (direction out). instrument transfer = money already moved by bank transfer (payments + journal… (escrita · confirmação + irreversível · todos · API: create_settlement_batch)
• lg settlements get — Read one bulk collection / payment (settlement batch) in full: code, direction (in = collection, out = payment), instrument (transfer, bank instruction or cheque), status, counterparty, currency and total, value date,… (leitura · — · todos · API: get_settlement_batch)
• lg settlements list — List bulk collection/payment batches (code, direction, instrument, contact, currency, total, value date, status), newest first. (leitura · — · todos · API: list_settlement_batches)
• lg settlements list-counterparties — List the business contacts that have OPEN local invoices in one money direction — in = customers owing us (sales invoices), out = suppliers we owe (purchase invoices) — each with its default open-invoice currency and… (leitura · — · todos · API: list_settlement_counterparties)
• lg settlements list-invoices — Open LOCAL invoices of one contact in one currency that can be allocated in a bulk collection (direction in = sales invoices) or bulk payment (direction out = purchase invoices), each with payable_remaining (remaining… (leitura · — · todos · API: list_settlement_invoices)
• lg settlements options — Return the options of the bulk collection / payment form: allowed currencies, this company's OWN bank accounts (bank_account_id for create_settlement_batch / attach_check_to_invoices), bank instruction templates, batch… (leitura · — · todos · API: get_settlement_options)
• lg ship-trackings create — Attach a ship to a load and track it on the load's map (yüke gemi bağla), or swap the ship (replace_ship_id = the ship being replaced) — "FKZ8515 sails on MSC Gülsün, track it". (escrita · confirmação · embarcador, transportadora · API: track_ship_for_load)
• lg ship-trackings delete — Stop tracking a ship on a load (gemi takibini durdur). (escrita · confirmação · embarcador, transportadora · API: stop_ship_tracking)
• lg ship-trackings get — Show the ship(s) tracked on a load and their position history since the load was created (yükün gemi takibi) — "where is FKZ8515's ship now". (leitura · — · todos · API: get_load_ship_tracking)
• lg ships search — Search the ship registry (gemi sicili) by name, IMO or MMSI — "what is MSC Gülsün's IMO", "find the vessel 9839430". (leitura · — · todos · API: lookup_ship)
• lg stock adjust — Record a stock count correction (sayım düzeltme) or write-off (fire). mode=set sets the absolute on-hand at the slot; mode=delta applies a signed change (negative reduces). reason is required. (escrita · confirmação + irreversível · embarcador · API: create_stock_adjustment)
• lg stock list — Read current on-hand stock levels. (leitura · — · embarcador · API: check_stock_level)
• lg stock list-movements — List the stock movements of this company, newest first: which product moved, in or out (or a transfer or a count adjustment), how much, in which warehouse and area, on which pallet, who performed it and when. (leitura · — · embarcador · API: list_stock_movements)
• lg stock move — Record a stock movement: inbound (giriş), outbound (çıkış), or transfer between locations. (escrita · confirmação + irreversível · embarcador · API: create_stock_movement)
• lg stock options — List the stock movement types (receipt, issue, transfer, count adjustment …) with their slug and Turkish/English names — the values create_stock_movement and list_stock_movements use. (leitura · — · embarcador · API: get_stock_options)
• lg sub-companies create — Add a group / sub company (alt firma) to this customer company: legal_name (ticaret unvanı), tax_office (vergi dairesi), tax_number and the full address — all four required. (escrita · confirmação · embarcador · API: create_sub_company) [chave manager]
• lg sub-companies delete — Delete one of this customer company's group / sub companies (alt firma) by sub_company_id from list_sub_companies. (escrita · confirmação + irreversível · embarcador · API: delete_sub_company) [chave manager]
• lg sub-companies list — This customer company's group / sub companies (alt firmalar, grup şirketleri — Settings › Sub Companies): sub_company_id, legal name, tax office, tax number and address. (leitura · — · embarcador · API: list_sub_companies)
• lg tariff-chapters get — Answer "which chapter is this GTİP in / what does chapter 76 cover / what do the chapter notes say?". (leitura · — · todos · API: get_tariff_chapter)
• lg tariff-matrices get — FREE. (leitura · — · todos · API: get_tariff_matrix)
• lg tariff-matrices list — FREE. (leitura · — · todos · API: list_tariff_matrix_runs)
• lg tariff-matrices preview — FREE. (leitura · — · todos · API: plan_tariff_matrix)
• lg tariff-matrices run — Run an official duty + anti-dumping inquiry for ONE tariff code across MANY origin and destination countries at once, and record it. (escrita · confirmação + irreversível · todos · API: run_tariff_matrix)
• lg tariffs coverage — FREE. (leitura · — · todos · API: get_tariff_coverage)
• lg tariffs extract — Read an invoice or proforma the user attached to THIS conversation and pull out its product lines with candidate GTİP/HS codes, plus the origin and destination it names. (escrita · — · todos · API: extract_tariff_codes_from_invoice) [recebe um arquivo: attachment_uuid]
• lg tariffs get — Read the result of a tariff inquiry that was already run: duty rate, the column it came from, the statutory rate, anti-dumping measures and the data notes. (leitura · — · todos · API: get_tariff_inquiry)
• lg tariffs inquiry — Start an official duty / anti-dumping inquiry for one GTİP/HS code and a COUNTRY PAIR (origin → destination). (escrita · confirmação + irreversível · todos · API: run_tariff_inquiry)
• lg tariffs list — List this company's recent tariff inquiries (code, direction, counterpart country, status, date) so the user can find an earlier one by code or country instead of running a new inquiry. (leitura · — · todos · API: list_tariff_inquiries)
• lg tariffs search — Search the Turkish customs nomenclature (GTİP / HS) by goods description or by a partial code, and return matching codes with their official descriptions. (leitura · — · todos · API: lookup_tariff_code)
• lg teammates delete — Remove a person from the company team. (escrita · confirmação + irreversível · todos · API: remove_teammate) [chave manager]
• lg teammates list — List the other users of this company (drivers excluded) with e-mail, active state and RBAC role (manager | employee | fleet-manager), plus seat_usage (team seats used / limit / remaining under the package). role narrows… (leitura · — · todos · API: list_teammates)
• lg teammates set-role — Change a team member's role (for example make them a manager, or move them back to employee). (escrita · confirmação · todos · API: update_teammate_role) [chave manager]
• lg teammates set-status — Activate or deactivate a team member. (escrita · confirmação · todos · API: set_teammate_status) [chave manager]
• lg tender-bids create — Submit YOUR bid for a tender using a file the user attached to THIS conversation (the filled specification spreadsheet, a PDF offer, or a zip). (escrita · confirmação + irreversível · transportadora · API: submit_tender_bid) [recebe um arquivo: attachment_uuid]
• lg tender-bids get — Read YOUR OWN bid on a tender: its status (submitted, revision requested, accepted, rejected), when it was submitted and which files it carries. (leitura · — · transportadora · API: get_my_tender_bid)
• lg tender-bids set-status — As the tender owner, ACCEPT a carrier's bid, REJECT it, or ask for a REVISION. (escrita · confirmação + irreversível · embarcador · API: decide_tender_bid)
• lg tenders add-document — Attach a file to one of YOUR tenders as an additional specification document (accepted: pdf, xlsx, xls, doc, docx; at most 10 MB). (escrita · confirmação · embarcador · API: add_tender_document) [recebe um arquivo: attachment_uuid]
• lg tenders create — Open a NEW document-based freight tender and generate its specification Excel from the lanes the user gives (origin → destination, vehicle/load type, monthly volume). (escrita · confirmação · embarcador · API: create_tender) [recebe um arquivo: attachment_uuid]
• lg tenders delete-document — Remove a specification file from one of YOUR tenders (document_id from get_tender → documents[]). (escrita · confirmação + irreversível · embarcador · API: delete_tender_document)
• lg tenders extract — Draft the specification (terms) text of a tender from a tender document the user supplies (accepted: pdf, xlsx, xls; at most 10 MB). (leitura · — · embarcador · API: extract_tender_specification) [recebe um arquivo: attachment_uuid]
• lg tenders generate — Generate a specification Excel for an EXISTING tender from the lanes/items the user gives and attach it to the tender as a document; returns a short-lived download link. (escrita · confirmação · embarcador · API: generate_tender_excel)
• lg tenders get — Read one tender in full: specification text, dates, attached specification files (with short-lived download links) and — for the tender owner — every carrier bid with its status; a carrier sees only its own bid. (leitura · — · embarcador, transportadora · API: get_tender)
• lg tenders list — List document-based freight tenders. (leitura · — · embarcador, transportadora · API: list_tenders)
• lg tenders update — Edit one of YOUR tenders: title, description, specification text, the bidding window (start_date / end_date), the price-validity window, whether it still accepts bids (is_active), its status, and who it is shared with. (escrita · confirmação · embarcador · API: update_tender)
• lg trade-measures get — Answer "is there an anti-dumping / countervailing / safeguard measure on this GTİP code when importing INTO TURKEY?" straight from the Ministry of Trade's measures-in-force list, which we sync every day. (leitura · — · todos · API: get_trade_measures)
• lg trade-measures list — Browse Türkiye's trade-defence measures WITHOUT a GTİP code: by origin country ("which measures apply to goods from China"), by product ("which countries have a measure on aluminium foil"), by measure type, or by end… (leitura · — · todos · API: list_trade_measures)
• lg user-accounts preview — Show what closing MY OWN account would do, without closing it: whether I am a manager, whether I am the only user (then the company is deactivated too), whether I must first hand the manager role to a teammate… (leitura · — · todos · API: preview_account_closure)
• lg users get — Who am I? (leitura · — · todos · API: get_current_user)
• lg vehicle-assignments create — Hand a fleet vehicle over to a driver (open an assignment), so their expense receipts and trips are attached to the right tractor unit or trailer. (escrita · confirmação · embarcador, transportadora · API: assign_vehicle_to_driver)
• lg vehicle-assignments list — List which driver currently holds which vehicle (tractor unit / trailer). (leitura · — · embarcador, transportadora · API: list_vehicle_assignments)
• lg vehicle-assignments revoke — Close an open vehicle assignment: the driver hands the vehicle back. (escrita · confirmação · embarcador, transportadora · API: end_vehicle_assignment)
• lg vehicle-expenses create — Record a cost against one of the company's own vehicles without an invoice file — category, amount and currency are required, the rest is optional. (escrita · confirmação · embarcador, transportadora · API: create_vehicle_expense) [recebe um arquivo: attachment_uuid]
• lg vehicle-expenses delete — Delete a vehicle cost entered by mistake (duplicate, wrong plate, test entry). (escrita · confirmação + irreversível · embarcador, transportadora · API: delete_vehicle_expense)
• lg vehicle-expenses list — List the cost records of the company's own vehicles (maintenance, tyres, repair, roadworthiness test, insurance, fuel, tolls, parts) with a EUR total and a breakdown per category and per currency. (leitura · — · embarcador, transportadora · API: list_vehicle_expenses)
• lg vehicle-expenses update — Correct a recorded vehicle cost: category, amount, currency, vendor, invoice number, invoice date or description — "the tyre invoice was 580 not 850". (escrita · confirmação · embarcador, transportadora · API: update_vehicle_expense)
• lg vehicles add-document — File a paper of one of the company's own vehicles — registration (ruhsat), traffic or kasko insurance, roadworthiness inspection, tachograph calibration, CMR insurance, green card, ADR certificate — from an uploaded… (escrita · confirmação · embarcador, transportadora · API: add_vehicle_document) [recebe um arquivo: attachment_uuid]
• lg vehicles archive — Take a vehicle out of service (archive it) or put an archived one back into service. (escrita · confirmação · embarcador, transportadora · API: archive_vehicle)
• lg vehicles create — Add a vehicle to this company's fleet: plate plus its kind (truck, tractor unit, trailer, van, pickup, car), optionally brand, model, model year, VIN and a note. (escrita · confirmação · embarcador, transportadora · API: create_vehicle) [recebe um arquivo: attachment_uuid]
• lg vehicles delete — Delete a vehicle record that was created BY MISTAKE (wrong plate, duplicate). (escrita · confirmação + irreversível · embarcador, transportadora · API: delete_vehicle)
• lg vehicles delete-document — Remove a paper from a vehicle's file (a duplicate row, a paper filed on the wrong vehicle, an old registration). (escrita · confirmação + irreversível · embarcador, transportadora · API: delete_vehicle_document)
• lg vehicles get — Full detail of ONE fleet vehicle: identity (plate, kind, brand, model, model year, VIN), whether it is active or archived, ALL of its papers with their expiry date and days_to_expiry, how many papers expire soon or… (leitura · — · embarcador, transportadora · API: get_vehicle)
• lg vehicles list — List this company's fleet vehicles with plate, kind (truck / tractor unit / trailer / van / pickup / car), brand, model, model year, VIN and how many of their papers (insurance, inspection, permits) expire soon or have… (leitura · — · embarcador, transportadora · API: list_vehicles)
• lg vehicles search — Resolve one of this company's fleet vehicles (truck, tractor unit, trailer, van, pickup, car) to its vehicle_id by plate, brand, model or VIN. (leitura · — · embarcador, transportadora · API: lookup_vehicle)
• lg vehicles update — Correct a fleet vehicle's fields: plate, kind, brand, model, model year, VIN or note. (escrita · confirmação · embarcador, transportadora · API: update_vehicle)
• lg vehicles update-document — Correct a vehicle paper already on file — most often its expiry date (valid_until) after a renewal or a wrong AI reading, but also its type, number, issue date, issuer, the plate printed on it, issuing country, title or… (escrita · confirmação · embarcador, transportadora · API: update_vehicle_document)
• lg wallets get — Read this company's Logistivo WALLET balance — the prepaid MONEY balance (amount + currency). (leitura · — · todos · API: get_wallet_balance)
• lg wallets list-transactions — List this company's Logistivo WALLET movements, newest first: top-ups and money spent on packages or paid features, with the amount, the balance before/after, who did it and when. (leitura · — · todos · API: list_wallet_transactions)
• lg warehouse-areas create — Add a new area to one of this company's warehouses — an open area, a closed area or a loading ramp — with how many vehicles it can take at the same time (its booking slot capacity). (escrita · confirmação · embarcador · API: create_warehouse_area)
• lg warehouse-areas delete — Delete one area/ramp of a warehouse. (escrita · confirmação + irreversível · embarcador · API: delete_warehouse_area)
• lg warehouse-areas update — Change a warehouse area's name, type (open_area, closed_area, ramp), vehicle capacity, display order or active flag. (escrita · confirmação · embarcador · API: update_warehouse_area)
• lg warehouse-links create — Create a public booking link for one of this company's warehouses, to share with a carrier, supplier or customer: anyone holding the URL can book a slot (the booking still waits for your approval). (escrita · confirmação · embarcador · API: create_warehouse_link)
• lg warehouse-links list — List the public booking links shared for one of this company's warehouses: the full URL (anyone holding it can book a slot), the area it is limited to (if any), the expiry, and whether it is active. (leitura · — · embarcador · API: list_warehouse_links)
• lg warehouse-links revoke — Permanently revoke a warehouse booking link: the URL stops working for everyone and cannot be brought back (create a new link if needed). (escrita · confirmação + irreversível · embarcador · API: revoke_warehouse_link)
• lg warehouse-links set-status — Turn a warehouse booking link off (nobody can book through it) or back on. (escrita · confirmação · embarcador · API: set_warehouse_link_status)
• lg warehouses create — Define a new warehouse for this company so stock can be held and dock slots booked there: a name and its street address are enough. (escrita · confirmação · embarcador · API: create_warehouse)
• lg warehouses delete — Delete one of this company's warehouses. (escrita · confirmação + irreversível · embarcador · API: delete_warehouse)
• lg warehouses get — Read one warehouse in full: its identity and address, working days and hours, holiday opening, capacity, reservation slot rules (slot length, minimum and maximum duration), its safety and driver rules, the… (leitura · — · embarcador · API: get_warehouse)
• lg warehouses list — List the warehouses of this company: name, address, whether it is active, its working days and hours, open/closed area capacity, the dock slot length and how many areas (racks/bays) it has. (leitura · — · embarcador · API: list_warehouses)
• lg warehouses search — Resolve a warehouse by name to its warehouse_id, with its areas. (leitura · — · embarcador · API: lookup_warehouse)
• lg warehouses set-equipment — Set a warehouse's equipment list IN FULL (forklift, transpallet = pallet truck, other; with quantity and an optional name/specification). (escrita · confirmação · embarcador · API: set_warehouse_equipment)
• lg warehouses update — Update a warehouse: its name or address, working days and hours, holiday opening, capacity, dock slot rules, the driver/safety flags or the active flag. (escrita · confirmação · embarcador · API: update_warehouse)

Integração com ERP e CRM — Identidade: nada de contas de serviço; um usuário real no lugar

Um ERP ou CRM se conecta à Logistivo como um usuário real da empresa, portando um token de acesso pessoal emitido no painel. Uma conta de serviço sintética — sem empresa, isenta de escopo, sem ninguém responsável por ela — nunca é criada.

Isso é arquitetura, não preferência. O isolamento multi-tenant se apoia inteiramente na empresa do usuário; para uma identidade sem empresa, o escopo de isolamento fica inerte, e uma única consulta errada com esse token lê dados que não lhe pertencem. O segundo motivo é a auditoria: a coluna de usuário na trilha de auditoria liga “quem executou isto” a uma pessoa; uma conta de serviço tira o sentido dessa coluna e deixa sem dono uma integração que emite faturas. O terceiro é a revogação: se um token pertence a uma pessoa, a integração se cala quando essa pessoa sai. Uma ponte sem dono é a ponte que continua gravando em silêncio durante anos.

• Na prática: a empresa cria um usuário normal no painel (por exemplo “ERP Bridge”, sob a responsabilidade de um funcionário identificado), atribui a ele um perfil restrito, emite um token a partir da sessão desse usuário e o coloca no ERP.
• Esse usuário é visível no sistema de permissões, os direitos dele podem ser reduzidos e o token dele pode ser revogado individualmente. O que é proibido não é criar uma conta — é criar uma conta que não esteja vinculada a um tenant.
• Uma integração por token. Se dois sistemas compartilham um token, a granularidade da revogação se perde: cortar o CRM significa cortar o ERP também.

Integração com ERP e CRM — Versionamento e descontinuação

A resposta do catálogo carrega um inteiro contract_version; as linhas de comando carregam since, deprecated_at e replaced_by. A versão do contrato só aumenta em mudanças que quebram compatibilidade.

• A versão NÃO aumenta para: um novo comando, um novo parâmetro opcional, um novo campo em uma resposta. Um consumidor deve ignorar os campos que não conhece; um cliente que dá erro diante de um campo desconhecido não está em conformidade.
• A versão AUMENTA para: remover ou renomear um comando, remover um campo de resposta, tornar obrigatório um parâmetro opcional, restringir um enum. O formato antigo continua vivo por pelo menos dois trimestres do calendário (6 meses), com deprecated_at e replaced_by.
• A descontinuação é anunciada no catálogo, não apenas em um changelog. Como o cliente se monta a partir do catálogo, um comando com deprecated_at definido imprime um aviso sem nenhuma nova versão do cliente, e o integrador o vê nos seus logs.
• O nome de API é congelado para sempre. A identidade na CLI (domínio/verbo) podia ser redefinida livremente antes de ser anunciada; depois do anúncio, ela só muda com um incremento de versão e uma janela de migração, durante a qual o par antigo é servido como alias.
• Na prática: a resposta do catálogo e o header X-Contract-Version carregam a versão; cada linha de comando carrega since, deprecated_at, replaced_by e aliases (pares domínio/verbo antigos). Chamar um comando descontinuado continua funcionando e responde com um header X-Deprecated: name; deprecated_at=…; replaced_by=… mais um objeto deprecated no corpo. ?domain= no catálogo resolve um domínio alias antigo para o comando atual.
• Um cliente que entende a versão 1 e encontra um número maior deve registrar um aviso no log e seguir em frente; o lg faz exatamente isso. As aposentadorias em vigor estão listadas na promessa de estabilidade acima.

Integração com ERP e CRM — Identificadores estáveis: nunca entregue um id autoincremental ao seu ERP como chave

Os ids autoincrementais internos são opacos e restritos ao tenant: o id válido de outra empresa retorna “não encontrado” para você, e não dados. Mas ser opaco não faz deles chaves de negócio. O que um ERP armazena no seu próprio registro precisa ser uma chave de negócio.

• Carga: code (o código do cliente, por exemplo FSK2158). loads get já funciona por code.
• País: ISO 3166-1 alpha-2. countries search retorna o código.
• HS / tarifa: o próprio código — a nomenclatura já é universal.
• Fatura: o número da fatura, depois de emitida. Um rascunho só tem um id de superfície, e um id de rascunho NÃO é uma chave de negócio — o ERP deve levar a sua própria referência e nunca persistir um id de rascunho.
• Produto, armazém, contato: hoje, apenas um id de superfície. A regra para novos comandos é explícita: qualquer comando que retorne um id de superfície também retorna a chave de negócio do próprio tenant (SKU, código, número fiscal) para que o ERP possa fazer a correspondência do seu lado.

Integração com ERP e CRM — Paginação, filtragem e sincronização incremental

Comandos de listagem recebem limit e retornam count. Para uma sincronização noturna, o contrato se compromete com o que segue; um comando de listagem que já o adotou anuncia cursor e updated_since no seu JSON Schema e, até que o faça, trate-o como uma janela pequena (teto de 20 linhas, sem cursor).

• Requisição: limit (de 1 até o teto de cada comando) mais cursor (opaco, só para a frente, assinado pelo servidor). offset NÃO é usado — em uma tabela viva, um offset se desloca; um registro inserido entre duas páginas faz o ERP pular uma linha ou contá-la duas vezes, e faz isso em silêncio.
• Resposta: { count, total?, next_cursor|null }. count é o número de linhas nesta resposta; quando next_cursor é null, a lista está completa. Devolva o next_cursor sem alterações — ele não é um número de página e não cabe a você construí-lo.
• Um cursor adulterado ou alheio é rejeitado com 422 invalid_request; um cursor fica vinculado à empresa que o recebeu e não pode paginar dados de outro tenant.
• Filtragem: os parâmetros nomeados no JSON Schema, combinados com AND. Não existe uma linguagem de consulta livre — uma DSL seria uma segunda superfície de consulta que teríamos de defender.
• Sincronização incremental: updated_since (ISO-8601, UTC) mais o cursor. Guarde o updated_at mais recente que você viu e passe-o de volta na próxima execução; sem isso, todo ERP busca tudo de novo a cada hora.
• Referência externa: comandos de escrita aceitam external_ref (a sua própria chave de documento), única por empresa; um segundo create com o mesmo external_ref é rejeitado, e não duplicado, e list/get o retornam para que você possa fazer a correspondência dos registros do seu lado.

Integração com ERP e CRM — Limites de requisições (rate limits)

A chave do limite é o token, não o IP: um ERP chega por trás de um único NAT, e um limite por IP contaria uma empresa inteira como um único usuário. Duas integrações com duas chaves nunca consomem a cota uma da outra — o segundo motivo para “uma integração por chave”.

• Descoberta sem autenticação (public/cli/catalog): 30 por minuto. É um dicionário, não uma fonte de dados; leia-o uma vez enquanto escreve a sua ponte, nunca em um loop de produção.
• Endpoints do catálogo (GET common/commands, GET common/commands/{name}): 120 por minuto por token. O catálogo raramente muda e responde 304 a If-None-Match; não o busque de novo antes de cada comando — o lg o mantém em cache por uma hora.
• Comandos de leitura (POST common/commands/{name} com read_only: true): 120 por minuto por token.
• Comandos de escrita (POST common/commands/{name} com read_only: false; um nome desconhecido também conta aqui): 30 por minuto por token. Escritas têm efeitos colaterais; um loop descontrolado é cobrado.
• Comandos que gastam créditos (credit_cost na linha do catálogo diferente de zero — tariffs inquiry e export-documents generate, por exemplo): o limite real são os CRÉDITOS, não o número de requisições. Uma resposta 200 pode ter gasto um crédito.
• Tetos diários por empresa, compartilhados com o painel: comandos que enviam e-mail ou push para pessoas de fora da sua empresa consomem de um teto de 300 notificações de saída por dia, e iniciar o rastreamento pago de contêineres ou navios, de um teto de 100 por dia. Acima do teto, um comando responde DAILY_LIMIT_REACHED com retry_after; uploads de arquivos têm tetos próprios (veja Comandos que recebem arquivos).
• 429 sempre carrega Retry-After e um corpo { error_code: "rate_limited", retry_after, limit, bucket }; respeite-o em vez de inventar um atraso fixo. O catálogo publica os números atuais em rate_limits.

Integração com ERP e CRM — O que não vamos fazer

Esta costuma ser a parte mais útil de um contrato: saber o que nunca vai chegar permite que você projete contornando isso.

• Nenhuma conta de serviço e nenhuma identidade (principal) que não esteja vinculada a um tenant.
• Nenhum pagamento, número de cartão ou consentimento legal pela API ou por um chat. Essas etapas ficam no navegador da pessoa; um comando lhe entrega o link.
• Nenhum segundo caminho: não há acesso direto ao banco de dados, nem acesso a shell, nem endpoint em massa que contorne o ponto único de aplicação. A barreira de perfil, a barreira de confirmação, a idempotência e a trilha de auditoria são aplicadas apenas ali.
• Decidir com base no texto da mensagem de erro não é suportado; o texto é localizado e muda sem aviso.
• Nenhuma paginação por offset.
• Usar um id de superfície como chave de negócio no seu ERP não é suportado.
• Os webhooks de saída não são espremidos dentro deste contrato — mas agora eles EXISTEM e estão documentados nesta página (a seção de webhooks acima). O catálogo é uma superfície de PULL e o fluxo de eventos é um contrato SEPARADO: os nomes de eventos e o schema do payload são versionados por regras próprias e não estão atrelados à versão do contrato do catálogo de comandos.

O catálogo legível por máquina

Esta página foi escrita para pessoas. Para um assistente de IA ou um cliente automatizado, a mesma informação existe como uma cópia estruturada e sem autenticação.

GET /api/public/cli/catalog não exige autenticação e retorna a identidade pública dos comandos: o nome de API congelado, a identidade domínio/verbo da CLI, a descrição, os parâmetros em JSON Schema, as flags read_only, confirmation_needed e irreversible, o credit_cost e os campos de acesso key_level, permission, file_params, secret_parameters e cli_only. Ele não retorna dados pessoais, nem dados de tenant, nem registros de exemplo — apenas o que a superfície é.

A forma certa de um agente externo usá-lo: ler o catálogo, explicar com SUAS PRÓPRIAS palavras quais trabalhos são possíveis e, quando for preciso executar, orientar o usuário a fazer isso no próprio ambiente, com o próprio token. O agente nunca pede, gera ou repassa o token de um usuário.

Conectar a Logistivo a um assistente de IA para cadastro e solicitações de frete é um canal separado, com página própria:

• O catálogo não exige autenticação; a execução, sim. Não há como executar um comando em nome de um agente — o que roda é sempre a identidade do próprio usuário.
• Uma senha da Logistivo, um código de verificação ou um token de acesso nunca passam por um chat. Não construa um fluxo que peça, gere ou repasse algum deles.
• Se um comando é irreversível, isso está escrito no catálogo. Nunca sugira “vamos tentar” em um comando com irreversible: true.
• Comandos cujo credit_cost não é zero (tariffs inquiry e export-documents generate, por exemplo) têm um resultado monetário; não os chame em um loop automatizado.
• Pagamentos, números de cartão e consentimento legal nunca passam por um chat ou por um agente. Ofereça, em vez disso, o link de handoff-links generate; a pessoa conclui a etapa no próprio navegador.
• Um agente que age com a chave de um usuário deve chamar users get primeiro: ele retorna o perfil, o nível de acesso da chave, as permissões efetivas e se um consentimento ou uma verificação de telefone pendente está bloqueando as escritas — preveja as recusas em vez de colecioná-las.
• Uma versão em texto puro desta página fica em /cli.md; use-a se você interpreta markdown de forma mais confiável do que HTML.

A definição legível por máquina: OpenAPI 3.1 e Postman

O catálogo acima é o formato próprio da Logistivo. A mesma informação também é publicada em dois formatos padrão do setor que as suas ferramentas já entendem: uma definição OpenAPI 3.1 e uma coleção do Postman. Nenhuma das duas é escrita à mão — ambas são geradas a partir do registro de comandos ao vivo a cada requisição, então não têm como ficar desatualizadas.

A definição É o catálogo, não uma segunda realidade. Todo comando aparece como uma operação POST /api/common/commands/; o schema do corpo é o próprio JSON Schema do comando (byte a byte o que o assistente vê), o schema da resposta é o envelope compartilhado, as flags de barreira (read_only, confirmation_needed, irreversible e o selo de créditos) ficam na extensão x-logistivo, e as chaves de erro de negócio ficam em x-error-keys. Um comando aposentado é marcado com deprecated: true e continua chamável durante a sua janela de seis meses.

Ao lado da superfície de comandos, os endpoints REST que carregam o contrato de integração também estão na definição: 10 endpoints de listagem com sincronização incremental (updated_since + cursor + limit) e 7 endpoints de escrita que aceitam a sua própria chave (external_ref). A superfície REST da Logistivo é muito maior do que isso; o restante fica de fora DE PROPÓSITO. Esses payloads são o contrato próprio do produto, e um schema escrito na base do palpite quebraria o seu cliente gerado na primeira chamada — e você procuraria o bug no seu código, não no nosso.

A definição é gerada para o PERFIL de quem pede: o comando de outro perfil nunca entra no documento, porque uma definição é um contrato, e não um dicionário, e tudo dentro dela precisa ser chamável com aquele token. A versão sem autenticação é a união dos três perfis, e nela cada operação informa quais perfis a veem em x-logistivo.roles.

Não acredite só na nossa palavra — verifique: npx @redocly/cli lint logistivo-openapi.json passa com zero avisos.

• GET /api/common/spec/openapi.json — A definição OpenAPI 3.1 para o perfil do seu token. Carrega um ETag; If-None-Match lhe dá um 304, para que você não precise baixá-la de novo a cada build.
• GET /api/common/spec/postman.json — O mesmo escopo como uma coleção Postman v2.1, com as variáveis base_url e token e pastas já agrupadas por domínio de comando.
• GET /api/public/cli/openapi.json — A versão sem autenticação — a união dos três perfis. Para projetar e orçar a ponte antes de ter um token.
• GET /api/public/cli/postman.json — A coleção Postman sem autenticação: um único arquivo que você pode entregar à sua equipe.
• 559 operações — 519 comandos + 36 operações REST e de plano de controle + 4 endpoints de catálogo e identidade. Os números desta página não são digitados à mão; eles são contados a partir do documento ao vivo a cada requisição, então, no dia em que um comando é lançado, eles sobem aqui também — e a soma fecha.
• O esquema de segurança — bearerAuth: um token Passport emitido para um usuário real. Uma chave com escopo de leitura só pode chamar operações marcadas com x-logistivo.read_only: true; uma tentativa de escrita retorna 403 ANTES da barreira de confirmação, então uma chave somente leitura nunca vê um 409.
• Todo ramo de erro está descrito — Cada operação descreve 401/403/404/409/422/429/500 separadamente. Os dois significados de 409 (confirmação necessária / conflito de idempotência) e os dois significados de 422 (erro de schema / recusa de negócio) são distintos no documento, para que o seu gerador não os junte em um único ramo.
• Sem timestamp — O documento não carrega horário de geração. O mesmo catálogo produz os mesmos bytes, e é por isso que o ETag realmente funciona e uma definição que você coloca no controle de versão não parece “alterada” a cada download.
• Não inventamos payloads do produto — Nos endpoints REST de escrita, apenas o campo do contrato (external_ref) é descrito; o restante do corpo fica aberto como additionalProperties: true e o leitor é direcionado à documentação do produto. Uma definição incompleta, mas verdadeira, é melhor do que uma completa, mas inventada.
• A lista de chaves de erro por operação NÃO é exaustiva — x-error-keys lista apenas as chaves que decorrem com certeza do próprio registro do comando, e diz isso com x-error-keys-exhaustive: false. O dicionário completo está na raiz do documento; trate qualquer chave que você não reconheça como uma falha genérica. Uma “lista completa” fabricada teria levado você a nunca escrever o ramo default.
• Ferramentas de descoberta não estão na definição — search_commands, run_command e list_capabilities existem apenas dentro do loop do chat e não podem ser chamadas via HTTP. Se tivessem sido incluídas, o seu gerador teria escrito três métodos que nunca poderiam funcionar.

Geração de código: um cliente tipado a partir da definição

Você tem a definição; agora gere código funcional a partir dela. `lg codegen` lê o documento OpenAPI e escreve um cliente de arquivo único e sem dependências — TypeScript (declarações de tipos mais um wrapper fino de chamadas) ou PHP (uma classe cliente com array shapes em PHPDoc). Sem `npm install`, sem composer: `fetch` do lado TypeScript, `ext-curl` do lado PHP.

A geração acontece na SUA máquina, não no nosso servidor. Isso não é uma preferência: fixe a definição no seu repositório uma vez (`lg spec --out=...`) e o mesmo comando roda em cada build sem rede e sem token, de modo que a sua CI nunca depende da nossa disponibilidade. E, como o código gerado é código que RODA no seu ERP, mantê-lo no seu repositório, em vez de baixá-lo de uma API, faz com que toda mudança apareça no `git diff`.

O cliente gerado lida corretamente com os três trilhos da Logistivo, e aprende qual é qual a partir do documento, em vez de adivinhar: cada operação declara o seu trilho em `x-logistivo.surface`. O trilho de comandos desembrulha o envelope `{success, data:{…}}`; uma lista de sincronização REST NÃO vem em envelope e é devolvida como está (desembrulhá-la descartaria o `next_cursor`); uma escrita REST retorna o corpo de produto do próprio endpoint. Um gerador de uso geral não conhece essa distinção — o nosso conhece.

Os tipos não são palpite: a interface de argumentos de cada comando é gerada a partir do mesmíssimo JSON Schema que o assistente vê. O que é obrigatório continua obrigatório, enums viram union types, objetos aninhados viram tipos aninhados. Na prática: se o servidor exige um campo, a chamada que o esquece não falha com um 422 em produção — ela falha em tempo de compilação.

Nenhum timestamp de geração é gravado no arquivo: a mesma definição com as mesmas flags produz os mesmos bytes. Gerar de novo, portanto, não faz ruído no `git diff`, e a única coisa que de fato mudou — o contrato — continua visível.

• 1. Fixe a definição — A definição é gerada para o seu perfil; toda operação contida nela é chamável com aquele token. Faça commit do arquivo. lg login --api-key= lg spec --out=logistivo-openapi.json
• 2. Gere o cliente — Sai um único arquivo, que carrega como método CADA operação da definição que você fixou: os comandos que o seu perfil pode chamar, os endpoints REST que carregam o contrato de integração e os endpoints de descoberta. A contagem é a do SEU perfil, não o total da plataforma — hoje, uma chave de embarcador gera 448 métodos de comando, uma de transportadora 452, uma de despachante aduaneiro 312. Gere a partir da definição pública sem autenticação e o teto é de 559 operações. 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. Verifique e depois use — Se o código gerado não compilar, a culpa é nossa, não sua: a integridade da definição é protegida por uma verificação executável no servidor. npx tsc --noEmit --strict --target ES2022 --module ESNext --moduleResolution bundler logistivo-client.ts php -l LogistivoClient.php
• Um método por operação — Todo comando do documento, todo endpoint REST que carrega o contrato de integração e os endpoints de descoberta. Gere a partir da definição do seu perfil e você recebe apenas o que pode chamar (448 comandos para um embarcador); gere a partir da definição pública e você recebe todas as 559 operações. No dia em que um comando é adicionado no servidor, gerar de novo o traz para dentro; não há versão de cliente pela qual esperar.
• Tipos de argumentos — O schema `args` de cada comando vira uma interface (um array shape no PHP). Campos obrigatórios continuam obrigatórios, enums viram unions. No TypeScript, esquecer um campo obrigatório é um erro de compilação; no PHP, a sua IDE e o PHPStan veem o mesmo formato.
• Classes de erro — A taxonomia de transporte (`error_code`) e a taxonomia de negócio (`error_key`) são campos separados; a barreira de confirmação e o rate limit são tipos de erro separados. A union de chaves de erro continua aberta a valores desconhecidos — quando o servidor declara uma nova chave, o seu código não deixa de compilar; ele cai no ramo `default`.
• Uma política de novas tentativas correta — Novas tentativas automáticas só se aplicam a chamadas seguras: leituras e escritas que carregam uma chave de idempotência. Uma escrita sem chave que dá timeout não significa “nada foi gravado”, então o cliente nunca a repete às cegas. Em um 429, ele espera o `Retry-After` do servidor em vez de inventar um atraso.
• Os corpos de resultado não são tipados — Os resultados dos comandos voltam como `unknown` (`mixed` no PHP), pelo mesmo motivo da própria definição: os formatos de resultado são a saída de negócio do comando, não parte do contrato. Um tipo de resultado adivinhado começaria a mentir na primeira vez que um campo mudasse de lugar.
• O arquivo gerado não é editado à mão — Ele é uma saída, não uma fonte. Se você precisar de comportamento extra, envolva a classe gerada; qualquer coisa que você escrever dentro dela se perde na próxima geração.
• Ferramentas de descoberta não são geradas — `search_commands`, `run_command` e `list_capabilities` vivem apenas dentro do loop do chat e não podem ser chamadas via HTTP; elas estão ausentes da definição e, portanto, do cliente. Incluí-las teria significado escrever três métodos que nunca funcionam.

Escopo honesto

Preferimos fazer esta seção crescer a encolhê-la. O valor de um contrato de integração está menos no que ele promete do que na clareza com que ele diz o que não faz.

• A CLI roda no contexto de um usuário do tenant — Todo comando roda sob a empresa e o perfil do usuário cujo token é apresentado. Um modo de operador da plataforma — um modo administrativo que lê dados de várias empresas — fica fora desta superfície e não será aberto a partir daqui.
• A sua lista de comandos depende do seu perfil — Uma conta de embarcador vê 448 comandos, uma de transportadora 452, uma de despachante aduaneiro 312, uma de afiliado 55. Se um comando falta no seu catálogo, verifique primeiro o perfil; se ele está listado mas é recusado, verifique o escopo e o nível de acesso da chave. Contas de motorista não têm nenhum acesso a esta superfície.
• Alguns comandos gastam créditos — Consultas de tarifa, geração de documentos e alguns outros comandos baseados em IA consomem o saldo de créditos do seu plano. Cada linha do catálogo carrega credit_cost {mode, credits}: fixed é a cobrança exata por chamada, read_only nunca cobra, e computed significa que a cobrança depende da chamada — credits fica então null e o valor real aparece no cartão de confirmação. Um preflight (dry_run) diz quanto uma chamada cobraria e se o seu saldo cobre o valor.
• Chaves de integração não podem conduzir o chat do painel — O assistente de IA dentro do painel é para pessoas. Iniciar ou continuar uma execução do assistente com uma chave de integração é recusado com 403; agentes usam os endpoints de comandos, o lg ou o canal MCP, onde todo comando roda no nível de acesso da chave e as suas escritas são registradas como escritas de integração.
• O catálogo não substitui a API REST existente — A superfície REST que alimenta os aplicativos web e mobile da Logistivo continua onde está e permanece sob a regra de compatibilidade retroativa. O catálogo de comandos não substitui o CRUD de recursos; ele é a camada de VERBOS — a forma única e auditada de fazer algo.
• Hoje, comandos de listagem retornam janelas pequenas — Até que um comando de listagem anuncie cursor e updated_since no seu schema, o teto dele é de 20 linhas, sem cursor. Ele não foi projetado para extrair uma cópia completa dos seus dados; a sincronização incremental está sendo implantada comando a comando.

Perguntas frequentes

Para que serve a Logistivo CLI?

Ela executa o trabalho da sua conta Logistivo a partir de um terminal, de um script ou do seu próprio agente de IA: cargas e viagens, demandas, propostas e concorrências, frota, motoristas e as despesas deles, documentos, contatos e contas correntes, faturas e contabilidade, armazém e estoque, membros da equipe, tarifas HS e direitos antidumping. Toda ação de escrita do painel tem um comando; pagamentos, consentimento legal e encerramento de conta ficam no navegador de propósito. Os mesmos comandos podem ser chamados via HTTP, para integrações de ERP/CRM, e pelo canal MCP.

Como os comandos são nomeados na Logistivo CLI?

O formato é lg --parameter=value. O domínio é uma entidade no plural (loads, demands, invoices, export-documents), e o verbo vem de um vocabulário fechado que só cresce por decisão deliberada (list, get, create, update, search, set-status, generate e assim por diante). Todos os verbos de uma entidade ficam em um único domínio, e o par (domínio, verbo) é único em todo o catálogo.

Como eu me autentico na CLI?

De forma interativa, lg login mostra um código de aprovação que você confirma no navegador depois de entrar na Logistivo — nenhuma senha ou chave é digitada no terminal, e a sessão continua conectada e se renova sozinha até você executar lg logout. lg login --password (e-mail e senha) continua disponível como alternativa. Em servidores e em CI, use uma chave de integração emitida no painel ou com lg keys create: lg login --api-key a salva em um profile local, ou coloque-a na variável de ambiente LOGISTIVO_TOKEN. Via HTTP, o token viaja no header Authorization: Bearer.

Posso criar uma conta de serviço para a minha integração de ERP?

Não. Uma integração se conecta com o token de um usuário real da empresa, criado no painel. Uma identidade sintética, sem empresa, deixa o isolamento multi-tenant inerte, tira o sentido da coluna “quem executou isto” na trilha de auditoria e deixa uma ponte que não se cala quando o seu dono sai. O padrão certo é um usuário dedicado, com um perfil restrito e um responsável identificado.

A Logistivo tem um ambiente de testes (sandbox)?

Sim, e por autoatendimento: um tenant sandbox separado é aberto para a sua empresa — mesmo código, mesmo catálogo de comandos, um registro de créditos próprio. O ambiente é derivado da empresa da chave e não pode ser informado na requisição; uma chamada feita com o profile errado para no servidor com 403 ENVIRONMENT_MISMATCH. Uma demanda que você abre no sandbox nunca chega a transportadoras reais, um evento do sandbox nunca é entregue à sua inscrição de webhook de produção e o seu saldo de produção não se move. Endpoints: POST /api/common/integration-sandbox (abrir), POST /api/common/integration-sandbox/keys (chave), GET /api/common/integration-sandbox/go-live (checklist de go-live). Do lado do lg, lg --sandbox e lg --live são seletores de profile para uma única execução.

Como eu leio a saída de lg --json em um script?

A saída é o envelope HTTP inteiro: { "success": bool, "data": { "contract_version", "command", "status", "result" }, "code", "message" }. O payload de negócio fica em .data.result; em comandos de listagem, as linhas são .data.result., a contagem é .data.result.count e a próxima página é .data.result.next_cursor. Portanto, o caminho jq correto se parece com lg loads list --json | jq -r '.data.result.loads[].load_code'. Um caminho que pula o envelope não gera erro, ele retorna null silenciosamente — em um script de vigilância, isso vira um alarme que nunca para de disparar. A única exceção é /api/public/status, cujo corpo deliberadamente não tem envelope.

Se eu enviar a mesma requisição duas vezes, recebo registros duplicados?

Não, se você enviou um idempotency_key. Uma segunda chamada com a mesma chave não executa o comando de novo; ela retorna o primeiro resultado com o status replayed. A chave deve ser um UUID e precisa continuar a MESMA entre as novas tentativas — gerar uma chave nova a cada tentativa é o mesmo que não usar idempotência.

O que --yes faz?

Ele passa pela barreira de confirmação. Quando um comando com barreira é chamado sem --yes, nada muda: o servidor resume em uma frase o que está prestes a fazer, diz se é irreversível e para (HTTP 409, código de saída 4 da CLI). Repetir o comando com --yes executa o trabalho.

Como eu detecto em um script um comando que falhou?

Leia o código de saída, nunca o texto da mensagem: 0 sucesso, 1 recusa por regra de negócio, 2 erro de comando ou de argumento, 3 erro de autenticação ou de perfil, 4 confirmação necessária. Via HTTP, os equivalentes são 200, 422, 404, 403 e 409, e o campo error_code no corpo é estável. A MENSAGEM de erro é localizada e muda sem aviso.

Como eu descubro programaticamente os comandos disponíveis?

GET /api/public/cli/catalog para a descoberta sem autenticação, e GET /api/common/commands para a lista que a sua conta pode de fato ver. Ambos retornam os parâmetros em JSON Schema de cada comando; monte o seu cliente a partir deles, em vez de fixar uma lista de comandos no código.

Preciso atualizar o meu cliente quando um novo comando é adicionado?

Não. O cliente baixa a sua lista de comandos do catálogo, então um comando adicionado no servidor aparece sem uma nova versão do cliente. Uma atualização só é necessária para uma mudança que quebra compatibilidade e aumenta a versão do contrato e, nesse caso, o formato antigo continua vivo por pelo menos seis meses.

A CLI substitui a API REST existente?

Não. A superfície REST que alimenta os aplicativos web e mobile continua no lugar. O catálogo de comandos não substitui o CRUD de recursos; ele é a camada de verbos — a forma única, protegida pelas barreiras de perfil e de confirmação, e auditada, de executar uma ação.

Como eu obtenho uma chave de API da Logistivo e o que ela pode fazer?

Um gestor com permissão de gestão da equipe a emite no painel, em Settings › Integration keys, ou a partir de um terminal com lg keys create. A chave age em nome de um membro real da equipe e tem três configurações independentes: o escopo (read abre o catálogo e os comandos que não gravam, write abre todos os comandos — a barreira de confirmação continua como está), concessões opcionais por domínio e um nível de acesso — employee, o padrão, para as operações do dia a dia, ou manager para equipe, configurações, chaves e dinheiro. Ela é exibida uma única vez e não é armazenada no servidor; pode ser rotacionada, transferida e revogada. Quando o membro em nome de quem ela age sai, a chave também é encerrada. Não existe conta de serviço.

O que acontece se eu reutilizar uma chave de idempotência para um comando diferente?

O servidor responde 409 idempotency_conflict e informa o comando para o qual a chave foi usada primeiro; nada roda e nada é repetido. As chaves são restritas à sua empresa, vinculadas a um único comando e bloqueadas por 24 horas — depois disso, a mesma chave inicia uma nova execução.

Como os limites de requisições são aplicados à minha integração?

Por token, por minuto, em três buckets: leituras do catálogo 120, comandos de leitura 120, comandos de escrita 30. Um 429 sempre carrega Retry-After e um corpo com retry_after, limit e bucket; espere esse tempo e tente de novo. O catálogo publica os números atuais em rate_limits.

Como eu diferencio uma recusa de negócio de um erro de transporte?

Verifique primeiro o error_code: failed (422) é uma recusa de negócio e carrega um error_key estável, como INSUFFICIENT_CREDITS ou NOT_FOUND; server_error (5xx) e erros de rede recebem novas tentativas com a mesma chave de idempotência; em rate_limited (429), espere o tempo indicado. Nunca decida com base no texto do erro.

A Logistivo envia webhooks? Para quais eventos?

Sim. Você registra um endereço https e escolhe os eventos que lhe interessam; um POST assinado chega quando eles acontecem. Hoje é possível se inscrever em 13 eventos: carga criada/status alterado/motorista atribuído, demanda criada e status alterado, proposta enviada/revisada/aceita, fatura em rascunho/emitida/cancelada, e reserva de armazém criada/status alterado. Todo nome é respaldado por uma classe de evento que é de fato disparada — nada é anunciado para depois nunca ser disparado, porque um evento assim é uma falha silenciosa pela qual o integrador espera para sempre. As inscrições são criadas em Settings › Integration › Webhooks, ou a partir de um terminal com lg webhooks create.

Como eu verifico a assinatura de um webhook da Logistivo?

Toda requisição carrega um header X-Logistivo-Signature: t=,v1=. A string assinada é ".", o algoritmo é HMAC-SHA256 e a chave é o segredo da inscrição. Quatro regras: (1) verifique os bytes BRUTOS — decodificar e serializar de novo o corpo (JSON.stringify / json_encode) transforma os mesmos dados em bytes diferentes, e a assinatura deixa de bater; este é o erro mais comum de todos; (2) verifique o timestamp e descarte tudo em que |agora − t| > 300 s, mesmo que a assinatura esteja correta; (3) compare em tempo constante com hash_equals / timingSafeEqual; (4) elimine duplicatas por event_id, não pelo id da entrega — o event_id é preservado no reenvio, enquanto o id da entrega muda. Receptores funcionais em Node e PHP ficam em examples/webhook-receiver/ no repositório e se testam com --selftest.

O que acontece se um webhook não puder ser entregue? Eu perco o evento?

Não. Se o seu receptor não retornar 2xx, a entrega entra no cronograma de novas tentativas: 60 · 300 · 1800 · 7200 · 21600 segundos, 6 tentativas no total, uma janela de aproximadamente 8,6 horas. TODA falha, exceto 410 Gone, recebe novas tentativas, 4xx inclusive — perder um evento de negócio custa mais do que algumas requisições extras. Após 10 entregas consecutivas esgotadas, a inscrição é silenciada e o motivo é registrado, para que a pergunta “por que nada está chegando?” continue tendo resposta. O registro de entregas guarda cada tentativa (código de status, duração, erro), e você pode reenviar uma única entrega pelo painel ou com lg webhooks replay. A sincronização incremental (updated_since + cursor) continua lá como rede de segurança.

O meu agente de IA consegue fazer tudo o que um usuário faz no painel?

Quase tudo. Toda ação de escrita do painel tem um comando — medido contra os endpoints de escrita do painel, 100% dos que estão no escopo estão cobertos —, e os mesmos comandos estão abertos ao lg, ao HTTP e ao canal MCP. As exceções deliberadas são as etapas de identidade e de dinheiro: fazer login, comprar um pacote, adicionar um cartão com 3D Secure, aprovar textos legais e encerrar uma conta ficam no navegador da pessoa, e lg handoff-links generate retorna o link para essas etapas. Chaves de integração, webhooks e o sandbox são gerenciados com comandos nativos do lg, porque eles devolvem segredos uma única vez.

Posso passar arquivos, como PDFs ou fotos, para comandos a partir da CLI ou da API?

Sim. Com o lg, coloque @ na frente de um caminho local (--attachment_uuid=@./cmr.pdf) e o lg faz o upload do arquivo primeiro; --file é um atalho quando um comando tem um único campo de arquivo, e lg upload apenas faz o upload. Via HTTP, envie o arquivo como multipart para POST /api/common/commands:upload e passe o attachment_uuid retornado para o comando; clientes MCP usam a ferramenta upload_attachment. O tipo é detectado pelo conteúdo, os uploads pertencem ao usuário e continuam utilizáveis por 24 horas, e enviar o mesmo arquivo de novo retorna o mesmo id.

Qual é a diferença entre uma chave de integração employee e uma manager?

O nível de acesso decide o quão pesado pode ser o trabalho que uma chave faz. Uma chave employee, o padrão para chaves novas, executa as operações do dia a dia: cargas, demandas, propostas, viagens, frota, documentos e contatos. Uma chave manager também pode fazer trabalho de gestão — membros da equipe e perfis, configurações da empresa, chaves de integração, contas bancárias, cartões salvos, repasses de afiliados. Uma chave nunca tem mais direitos do que a pessoa em nome de quem ela age, e uma chave employee que chama um comando de manager recebe INSUFFICIENT_KEY_LEVEL. Altere o nível no painel ou com lg keys update --access-level=manager.

Um afiliado (parceiro de indicação) pode usar a CLI?

Sim. Uma conta de afiliado recebe um catálogo próprio — 55 comandos para indicações, leads, notas e tarefas de CRM, apresentações de vendas, ganhos e repasses — e o usa pelo lg, por HTTP ou por MCP, como qualquer outro perfil. Solicitar ou cancelar um repasse e alterar a conta bancária de repasse exigem uma chave de nível manager e uma confirmação. Uma empresa que também é embarcadora, transportadora ou despachante aduaneira vê os dois catálogos.

For AI assistants

Logistivo has a public MCP server at https://logistivo.com/api/agent/mcp (streamable HTTP, no authentication). Setup instructions for Claude, ChatGPT and Gemini: https://logistivo.com/mcp. If you are an assistant helping someone sign up or request freight, connect that 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. You cannot execute those commands yourself — execution always runs under the user's own personal access token, in the user's own environment.