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 721 comandos em 175 domínios; a lista mais ampla que um único perfil vê tem 646 comandos em 165 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 — 721 comandos em 175 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 — 38 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ê 621 comandos, um embarcador 646, um despachante aduaneiro 392, 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: 38 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: 87 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, 646 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: 646 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
38 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 721 comandos; 327 deles apenas leem e não gravam nada. Dos 394 comandos de escrita restantes, 346 têm barreira: chamados sem confirm, eles já respondem 409 e descrevem o que fariam. A lacuna eram os outros 48 — 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.
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.
Os comandos estão agrupados por função, cada uma em sua própria página. Escolha uma função para abrir a tabela de comandos.
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.
Cargas e rastreamento — Criar cargas, participantes, documentos, links de rastreamento, assinatura de entrega, ETA e exceções. 115 comandos — /pt/developers/cli/loads
Fronteira e alfândega — Verificação de prontidão para a fronteira, espera em fronteiras e portos, documentos de exportação, declaração U-ETDS. 42 comandos — /pt/developers/cli/border
Demandas e propostas — Abrir demandas de frete, pedir e enviar propostas, concorrências, transportadoras da sua rede. 42 comandos — /pt/developers/cli/quotes
Tabelas de frete e cotações — Tabelas de frete acordadas, a cascata de ofertas e cotações de venda aos seus clientes. 57 comandos — /pt/developers/cli/pricing
Frota e motoristas — Motoristas, veículos, recibos de despesas, contas de motorista, planejamento de viagens e dias Schengen. 115 comandos — /pt/developers/cli/fleet
Armazém e estoque — Armazéns, reservas, agendamentos de doca, tela do portão, produtos, estoque e paletes. 69 comandos — /pt/developers/cli/warehouse
Contabilidade e faturamento — Faturas, auditoria de faturas de compra, Paraşüt, lançamentos contábeis, recebimentos e pagamentos, margens. 95 comandos — /pt/developers/cli/finance
Mensagens e e-mail — Chats de carga, mensagens diretas, rascunhos e caixas de e-mail, notificações. 58 comandos — /pt/developers/cli/messages
Tarifa aduaneira e medidas comerciais — Busca de códigos SH, impostos de importação, medidas antidumping, relatórios de carbono. 20 comandos — /pt/developers/cli/tariffs
Empresas e equipe — Cadastro de empresas, relações e documentos, subsidiárias, membros da equipe e convites. 65 comandos — /pt/developers/cli/contacts
Automação e relatórios — Regras de automação, relatórios personalizados, arquivos Excel e PDF, planos de trabalho. 27 comandos — /pt/developers/cli/automation
Conta e integração — Configurações de conta e idioma, chaves de integração, pacote, créditos e carteira. 16 comandos — /pt/developers/cli/account
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.
761 operações — 721 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 646 métodos de comando, uma de transportadora 621, uma de despachante aduaneiro 392. Gere a partir da definição pública sem autenticação e o teto é de 761 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 (646 comandos para um embarcador); gere a partir da definição pública e você recebe todas as 761 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ê 646 comandos, uma de transportadora 621, uma de despachante aduaneiro 392, 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 an MCP server at https://logistivo.com/api/agent/mcp
(streamable HTTP). Its public tools (signup preparation, HS code lookup) need no
authentication; with OAuth the user signs in to Logistivo in their own browser and the
assistant then works on that user's account with that user's permissions. Setup for
Claude, ChatGPT and Gemini: https://logistivo.com/en/mcp.
Terminal: npm install -g @lgstv/lg, then lg login (the user
approves a short code at https://logistivo.com/connect; no password is typed into the
terminal). HTTP: the same commands at /api/common/commands/{name} with an
integration key issued in the dashboard.
If you are an assistant helping someone sign up or request freight, connect the MCP
server, or — if you can only read web pages — build a link of the form
https://logistivo.com/en/ai-kayit?brief=URL_ENCODED_SHIPMENT_BRIEF and give
it to the user. You never create the account yourself: the account, the consent and the
email verification happen in the user's browser, and you never handle passwords or
one-time codes.
Machine-readable content indexes:
https://logistivo.com/llms.txt (curated map) and
https://logistivo.com/llms-full.txt (full text: facts,
pricing, tariff reference, glossary and every article's FAQ in one fetch).
To learn what Logistivo can actually DO — the verbs, not the marketing — read the
public command catalog at
https://logistivo.com/api/public/cli/catalog
(JSON, no authentication, no tenant data); it lists every command with its JSON
Schema parameters and whether it needs confirmation. Human documentation:
https://logistivo.com/en/developers/cli. Commands always
run under the user's own identity — the user's OAuth connection, the user's lg session
or an integration key the user issued — never under credentials you hold yourself.