Implementando integrações via API

Existem várias formas de integrar seus próprios sistemas, ou sistemas de terceiros, ao Gestor Logístico. Geralmente o caminho mais simples e rápido de ser implementado é através da troca de arquivos, usando e-mail ou SFTP. Também há padrões de mercado para as trocas de dados mais comuns — notas fiscais, conhecimentos de transporte, ocorrências e faturas — via EDI (veja aqui como funciona no Gestor Logístico).

Essas soluções funcionam bem em muitos casos, mas não atendem as situações em que a troca precisa acontecer em tempo real. Por exemplo: um portal de venda on-line (e-commerce) precisa exibir o valor do frete ao usuário no momento do check-out — o portal envia os dados dos produtos ao Gestor Logístico, que calcula o frete até o destino e devolve a informação imediatamente. É para isso que existe a API do Gestor Logístico: um conjunto de web services que permite a outros sistemas interagir com o GL de forma automatizada.

Considerações preliminares

Utilizar a API é a forma mais eficiente e segura de integrar seus sistemas com o GL. O processo pode ser totalmente automatizado, os dados são atualizados imediatamente, a comunicação é criptografada e todo o processo pode ser monitorado.

Porém, tudo tem um custo: é também o meio mais complexo de implementar. Você vai precisar envolver o time de TI da sua empresa, para que entendam o formato e as particularidades da nossa API e desenvolvam uma integração sob medida. Este artigo foi escrito exatamente para esse time.

Além disso, como o processo é automatizado — geralmente sem intervenção humana — ele precisa se recuperar sozinho de falhas transitórias (por exemplo, uma indisponibilidade momentânea de internet no instante em que seu sistema tenta enviar uma nota fiscal). Sua aplicação precisa tratar essas exceções e tentar novamente mais tarde (veja Tratamento de erros abaixo).

Especificações técnicas

A tecnologia adotada é RESTful, o formato mais comum hoje para esse tipo de integração. Os sistemas trocam dados no formato JSON. A comunicação é sempre por HTTPS, com todos os dados criptografados, e todos os acessos precisam ser autenticados e autorizados.

Um detalhe importante: a API do Gestor Logístico é a mesma que o próprio sistema usa. Tudo o que a interface web faz passa pelos mesmos endpoints que estão à sua disposição — ou seja, a API é completa e está sempre em produção, não é um "anexo" mantido à parte.

Autenticação

Para acessar a API você precisa de um usuário de integração cadastrado no sistema, com os direitos necessários liberados para as operações que sua integração vai realizar. Em caso de dúvida sobre como cadastrar esse usuário, envie um e-mail para o nosso time de suporte ou fale com o consultor que atende sua empresa.

O protocolo utilizado é o HTTP Basic Authentication: usuário e senha enviados no cabeçalho Authorization de cada chamada (as bibliotecas HTTP de todas as linguagens fazem isso por você — em curl, é a opção -u).

Endereço da API e versionamento

O endereço-base da API é único para todos os clientes e versionado:

https://api15.gestorlogistico.com.br

O "15" indica a versão da API. A versão publicada nunca recebe alterações que quebrem integrações existentes — mudanças estruturais entram numa versão nova. Na prática: o Gestor Logístico evolui continuamente, mas a sua integração continua funcionando na versão em que foi construída, sem que seu time de TI precise acompanhar cada mudança do produto.

Como a API identifica a sua empresa (instância)

Como o endereço é compartilhado por todos os clientes, cada chamada precisa ser direcionada à instância correta (o ambiente da sua empresa). Isso acontece de uma destas duas formas:

• Pelo usuário autenticado — quando o usuário está autorizado em uma única instância, a chamada vai direto para ela, sem configuração extra. É o caso típico de um usuário de integração, e é assim que os exemplos deste artigo funcionam;
• Pelo header Instancia-Id — forma explícita e mais segura, necessária quando o usuário tem acesso a mais de uma instância. Nesse caso, sua aplicação deve enviar esse header em cada chamada, com o identificador da instância desejada — solicite esse identificador ao nosso suporte.

Passo a passo: sua primeira chamada

Antes de desenhar a integração inteira, valide o acesso com uma consulta simples. O exemplo abaixo lista Ordens de Transporte (OTs) cadastradas em junho/2026, trazendo só a primeira página, com 10 itens e o nível de detalhe mínimo:

curl -g -u "usuario.integracao@suaempresa.com.br:SUA-SENHA" \
   "https://api15.gestorlogistico.com.br/ots?PeriodoCadastramento={Inicio:2026-06-01,Termino:2026-06-30}&NivelDetalhe=1&Conf={NumeroDaPagina:1,ItensPorPagina:10}"

Uma resposta como esta confirma que usuário, senha e direitos estão corretos:

{
   "itens": [
     {
       "id": 29008,
       "numero": 13936,
       "numeroFormatado": "13.936"
     }
   ],
   "totalItens": 132
 }

Três coisas para observar nessa chamada — todas são convenções que se repetem na API inteira e estão detalhadas nas seções seguintes:

• PeriodoCadastramento={Inicio:...,Termino:...} — nas consultas (GET), objetos vão na query string nesse formato compacto (ver convenções). Consultas de listas costumam exigir um período (limitado a ~92 dias por chamada);
• NivelDetalhe=1 — controla quanto detalhe cada objeto traz na resposta (ver níveis de detalhe);
• Conf={NumeroDaPagina:1,ItensPorPagina:10} — paginação (ver paginação).

Dica: se a chamada retornar erro 401, confira usuário/senha; se retornar uma mensagem de direito/permissão, o usuário de integração ainda não tem o direito de consulta liberado — fale com o administrador da sua conta ou com o suporte. E se o usuário tiver acesso a mais de uma instância, lembre-se de enviar o header Instancia-Id (ver seção anterior).

Como a API é organizada

Os endpoints seguem o padrão REST: cada recurso de negócio tem sua rota, e o verbo HTTP indica a operação — GET consulta, POST cria, PUT altera, DELETE remove. As principais famílias de rotas:

A lista completa — com todos os endpoints, parâmetros e schemas — está na página Documentação da API, agrupada por essas mesmas áreas de negócio.

Convenções de dados

• JSON em camelCase — e propriedades sem valor (null) são omitidas das respostas: se um campo não veio, é porque está vazio (ou porque o nível de detalhe pedido não o inclui — ver abaixo).
• Datas em ISO 8601 — ex.: 2026-06-30 ou 2026-06-30T14:00:00-03:00.
• Enums trafegam pelo valor inteiro. Campos de domínio fixo (tipo de pessoa, situação do documento, tipo de ocorrência…) enviam e recebem o número, não o nome. O significado de cada valor está na seção Models da página Documentação da API — cada enum é documentado uma única vez, e as propriedades que o usam apontam para ele.
• Consultas (GET) recebem objetos e listas na query string no formato JSV — parecido com JSON, mas sem aspas nas chaves e valores simples: ?Conf={NumeroDaPagina:1,ItensPorPagina:50}&ChavesNfes=[chave1,chave2]. Já nas operações de escrita (POST/PUT), o objeto vai no corpo da requisição, em JSON normal.

Nível de detalhe das respostas (NivelDetalhe*)

Este é o padrão mais importante para usar bem a API. Praticamente todas as consultas aceitam um ou mais parâmetros NivelDetalhe*, que controlam quanto de cada objeto vem na resposta:

Cada objeto relacionado costuma ter o seu próprio parâmetro. Em GET /ots, por exemplo, NivelDetalhe controla a própria OT e NivelDetalheDaots os documentos associados a ela. O efeito no tamanho é grande — a mesma OT consultada com NivelDetalhe=1 responde com ~0,3 KB (id, número), e com NivelDetalhe=3 responde com ~6,5 KB (unidade, origem/destino com endereço completo e coordenadas, remetente, destinatário, documentos, valores…).

Atenção ao ler os schemas da documentação:
Eles mostram todas as propriedades possíveis de cada objeto — o equivalente ao nível Completo. A resposta real traz só o subconjunto correspondente ao nível pedido. Se um campo do schema não veio na sua resposta, aumente o nível de detalhe do objeto correspondente. E use sempre o menor nível que atender sua integração: as respostas ficam menores e mais rápidas para os dois lados.

Paginação

As consultas de lista aceitam o parâmetro Conf, um objeto com a configuração da página e da ordenação:

?Conf={NumeroDaPagina:1,ItensPorPagina:50,CampoOrdenacao:Numero,DirecaoOrdenacao:2}

• NumeroDaPagina / ItensPorPagina — página desejada (começa em 1) e tamanho da página;
• CampoOrdenacao / DirecaoOrdenacao — campo de ordenação e direção (1 = ascendente, 2 = descendente);
• TodosOsItens:true — devolve tudo de uma vez, limitado a 10.000 linhas; acima disso a chamada falha pedindo paginação.

A resposta paginada tem sempre o mesmo formato — os itens da página e o total geral (para você calcular o número de páginas):

{ "itens": [ ... ], "totalItens": 132 }

Tratamento de erros

Erros retornam status HTTP 4xx/5xx com um objeto responseStatus no corpo, sempre com uma mensagem legível:

{
   "responseStatus": {
     "errorCode": "ApplicationException",
     "message": "O período máximo permitido para esta pesquisa é de 92 dias"
   }
 }

Duas famílias de erro pedem tratamentos diferentes:

• Erros de chamada (autenticação, permissão, dados inválidos, regras de negócio — como o período máximo acima): repetir a mesma chamada não resolve. Corrija a requisição;
• Falhas transitórias (rede, indisponibilidade momentânea): sua aplicação deve registrar a falha e tentar novamente mais tarde — de preferência com intervalo crescente entre tentativas.

Referência técnica: Documentação da API dentro do próprio sistema

Todo endpoint da API — parâmetros, formato de cada campo, o que cada operação retorna — está documentado numa página dentro do próprio Gestor Logístico, em Integrações → Documentação da API. É a fonte de referência mais confiável, porque é gerada automaticamente a partir do backend real: nunca fica desatualizada como um PDF ou um link externo.

Na página você encontra:

• Todos os endpoints organizados por área de negócio (as mesmas famílias da tabela acima);
• O schema completo de cada requisição e resposta, campo a campo, e o domínio de cada enum na seção Models;
• Os parâmetros de consulta documentados um a um — incluindo os NivelDetalhe* e os objetos de query string (com os campos aceitos em cada um);
• Exemplos de código prontos, gerados automaticamente para várias linguagens (curl, JavaScript, Python, C#, entre outras) para cada endpoint.
  
  

Dica: use essa página como checklist ao planejar uma integração nova — ela mostra exatamente o que existe hoje, sem depender de perguntar ao suporte "isso já existe?" a cada dúvida.

Para acessar, faça login normalmente no Gestor Logístico e abra o menu Integrações — a opção Documentação da API fica ao lado do Monitor de integrações. Se você não encontrar essa opção, é porque seu usuário ainda não tem o direito de acesso liberado — peça ao administrador da sua conta ou ao nosso suporte.

Essa página é somente leitura: ela documenta os endpoints, mas não executa chamadas por ali. Para integrar de fato, sua aplicação deve chamar a API diretamente, como mostrado no passo a passo acima.

Guias narrativos por processo

Para os processos de integração mais comuns, já temos um guia dedicado com o passo a passo completo:

• Simulação de fretes
• Envio de pedidos
• Envio de notas fiscais (NF-e)
• Importação de CT-es
• Recebimento das faturas das transportadoras
• Registro de ocorrências
• Importação de NFes de Inbound via SEFAZ

Não encontrou o processo que você quer automatizar nesta lista? Consulte a Documentação da API dentro do sistema (seção anterior) — ela cobre endpoints que ainda não têm um guia narrativo aqui. Se mesmo assim tiver dúvida, fale com nossa equipe de suporte.

Dúvidas?

Consulte a equipe de suporte pelo chat ou envie um e-mail para suporte@tecnovia.com.br.