---
title: Implementando integrações via API
description: TMS Gestor Logístico - Muitos dos serviços do Gestor Logístico podem ser utilizados de forma totalmente automatizada, via API.
---

[Pular para o conteúdo](https://ajuda.tecnovia.com.br/implementando-integrações-via-api#main-content)

[Abrir um chamado de suporte](https://ajuda.tecnovia.com.br/kb-tickets/new?hsLang=pt-br)

[![logo-tecnovia-sem-fundo-2000](https://ajuda.tecnovia.com.br/hs-fs/hubfs/logo-tecnovia-sem-fundo-2000.png?width=200&height=25&name=logo-tecnovia-sem-fundo-2000.png)](https://www.tecnovia.com.br/?hsLang=pt-br)

- [Blog](https://blog.tecnovia.com.br/)
- [Ajuda](https://ajuda.tecnovia.com.br/)

Abrir navegação principal

Fechar navegação principal

- [Blog](https://blog.tecnovia.com.br/)
- [Ajuda](https://ajuda.tecnovia.com.br/)
- [Abrir um chamado de suporte](https://ajuda.tecnovia.com.br/kb-tickets/new)

 Como podemos ajudá-lo?

- Não há sugestões porque o campo de pesquisa está em branco.

1. [Central de Ajuda do Gestor Logístico](https://ajuda.tecnovia.com.br/?hsLang=pt-br)
2. [Integrações](https://ajuda.tecnovia.com.br/integra%C3%A7%C3%B5es?hsLang=pt-br)

# Implementando integrações via API

## Muitos dos serviços do Gestor Logístico podem ser utilizados de forma totalmente automatizada, via API. Este guia mostra o caminho completo: da primeira chamada de teste até as convenções que valem para a API inteira.

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](https://kb.tecnovia.com.br/acessando-o-servidor-sftp-central-de-ajuda?hsLang=pt-br). 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](https://kb.tecnovia.com.br/o-que-%C3%A9-um-edi-central-de-ajuda?hsLang=pt-br) 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](https://ajuda.tecnovia.com.br/implementando-integrações-via-api#erros) abaixo).

### Especificações técnicas

A tecnologia adotada é [RESTful](https://restfulapi.net/), o formato mais comum hoje para esse tipo de integração. Os sistemas trocam dados no formato [JSON](https://pt.wikipedia.org/wiki/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](mailto:suporte@tecnovia.com.br) ou fale com o consultor que atende sua empresa.

O protocolo utilizado é o [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_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](https://ajuda.tecnovia.com.br/implementando-integrações-via-api#estrutura)). 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](https://ajuda.tecnovia.com.br/implementando-integrações-via-api#nivel-detalhe));
- `Conf={NumeroDaPagina:1,ItensPorPagina:10}` — paginação ([ver paginação](https://ajuda.tecnovia.com.br/implementando-integrações-via-api#paginacao)).

```
401
```

### 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:

| Rota (prefixo) | Recurso |
| --- | --- |
| `/ots`, `/daots` | Ordens de Transporte e seus documentos associados |
| `/dts`, `/pre-dts` | Documentos de Transporte (fretes contratados) |
| `/cargas`, `/viagens`, `/coletas-entregas` | Cargas, viagens e monitoramento |
| `/ctes`, `/nfes`, `/mdfes` | Documentos fiscais (CT-e, NF-e, MDF-e) |
| `/eventos`, `/ocorrencias` | Eventos e ocorrências de transporte |
| `/faturas-transportador`, `/auditorias-fretes` | Faturas de transportadoras e auditoria de frete |
| `/simulacoes`, `/cotacoes`, `/tabelas-de-frete` | Comercial: simulação e cotação de fretes |
| `/importacao-arquivos`, `/arquivos` | Importação de arquivos (XMLs de NF-e/CT-e etc.) |
| `/transportadoras`, `/motoristas`, `/veiculos`, `/locais`… | Cadastros |

A lista completa — com todos os endpoints, parâmetros e schemas — está na página [Documentação da API](https://ajuda.tecnovia.com.br/implementando-integrações-via-api#referencia), 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**:

| Valor | Nível | O que vem na resposta |
| --- | --- | --- |
| `0` | NaoIncluir | o objeto não é incluído |
| `1` | Minimo | só a chave e os atributos mínimos (ex.: id e número) |
| `2` | Basico | os atributos principais, típicos de uma linha de listagem |
| `3` | Completo | todos os atributos do objeto |
| `4` | Nenhum | só as chaves das dimensões referenciadas (otimizado para carga de BI/Datawarehouse) |

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](https://ajuda.tecnovia.com.br/implementando-integrações-via-api#primeira-chamada) 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](https://ajuda.tecnovia.com.br/simulando-os-fretes-atrav%C3%A9s-da-api?hsLang=pt-br)
- [Envio de pedidos](https://ajuda.tecnovia.com.br/importando-pedidos-via-api?hsLang=pt-br)
- [Envio de notas fiscais (NF-e)](https://ajuda.tecnovia.com.br/importando-nfes-via-api?hsLang=pt-br)
- [Importação de CT-es](https://ajuda.tecnovia.com.br/importando-ctes-via-api?hsLang=pt-br)
- [Recebimento das faturas das transportadoras](https://ajuda.tecnovia.com.br/como-receber-via-api-as-faturas-das-transportadoras?hsLang=pt-br)
- [Registro de ocorrências](https://ajuda.tecnovia.com.br/registrando-ocorr%C3%AAncias-via-api?hsLang=pt-br)
- [Importação de NFes de Inbound via SEFAZ](https://ajuda.tecnovia.com.br/importando-nfes-de-inbound?hsLang=pt-br)

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](mailto:suporte@tecnovia.com.br).

- [Conceitos do Gestor Logístico](https://ajuda.tecnovia.com.br/conceitos-do-gestor-log%C3%ADstico?hsLang=pt-br)
- [Novidades](https://ajuda.tecnovia.com.br/novidades?hsLang=pt-br)
- [Configurações](https://ajuda.tecnovia.com.br/configura%C3%A7%C3%B5es?hsLang=pt-br)
- [Integrações](https://ajuda.tecnovia.com.br/integra%C3%A7%C3%B5es?hsLang=pt-br)
- [Aplicativo mobile (para motoristas)](https://ajuda.tecnovia.com.br/aplicativo-mobile-para-motoristas?hsLang=pt-br)
- [Informações gerenciais](https://ajuda.tecnovia.com.br/informa%C3%A7%C3%B5es-gerenciais?hsLang=pt-br)
- [Operações de Transporte](https://ajuda.tecnovia.com.br/opera%C3%A7%C3%B5es-de-transporte?hsLang=pt-br)
- [Documentos de Transporte](https://ajuda.tecnovia.com.br/documentos-de-transporte?hsLang=pt-br)
- [Ocorrências, tracking, transit-times](https://ajuda.tecnovia.com.br/ocorr%C3%AAncias-tracking-transit-times?hsLang=pt-br)
- [Faturas das transportadoras](https://ajuda.tecnovia.com.br/faturas-das-transportadoras?hsLang=pt-br)
- [Contratos, tabelas e simulações de fretes](https://ajuda.tecnovia.com.br/contratos-tabelas-e-simula%C3%A7%C3%B5es-de-fretes?hsLang=pt-br)
- [Legislação, normas e regulamentos](https://ajuda.tecnovia.com.br/legisla%C3%A7%C3%A3o-normas-e-regulamentos?hsLang=pt-br)
- [Navegação e produtividade](https://ajuda.tecnovia.com.br/navega%C3%A7%C3%A3o-e-produtividade?hsLang=pt-br)
- [Usuários de clientes](https://ajuda.tecnovia.com.br/usu%C3%A1rios-de-clientes?hsLang=pt-br)
- [Usuários de transportadoras](https://ajuda.tecnovia.com.br/usu%C3%A1rios-de-transportadoras?hsLang=pt-br)

[![logo 125x1000](https://ajuda.tecnovia.com.br/hs-fs/hubfs/logo%20125x1000.png?width=200&height=25&name=logo%20125x1000.png "logo 125x1000")](https://tecnovia.com.br?hsLang=pt-br)

Copyright © 2025, Tecnovia Soluções para Gestão Logística