Na maioria dos casos, as Notas Fiscais Eletrônicas (NFes) são a fonte principal de dados para a criação das Ordens de Transporte (OTs), que são os objetos mais importantes para todas as análises que serão feitas pelo Gestor Logístico. Este artigo explica em detalhes como fazer a importação das NFes via API.

Porém, em algumas situações, é desejável fazer a criação da OT no Gestor Logístico antes mesmo da emissão da NFe. É o caso, por exemplo, de quando desejamos fazer a composição das cargas e/ou roteirização, para só então gerar as NFes.

Temos algumas opções para a criação dos pedidos no GL:

Digitação manual: Se o volume de pedidos for pequeno, é possível cadastrá-los manualmente, diretamente na página de Ordens de Transporte;
Importação de planilha: É talvez a opção mais simples, basta preencher uma planilha com os dados básicos dos pedidos, e importá-la no sistema (também a partir da página de Ordens de Transporte). Veja aqui o layout da planilha a ser preenchida.
Para uma integração mais robusta e automatizada, a melhor alternativa é o envio via API, que é o que descreveremos abaixo.

Passo 1: Entendendo o formato da API

Este artigo explica os princípios básicos para utilização da API do GL, como formato dos dados, forma de autenticação, e URLs para acesso. Comece por ele!

Passo 2: Obtendo um usuário e senha para acesso

Obviamente, o acesso à API somente será autorizado se você possuir as "credenciais" que provem que você (ou melhor, neste caso a sua aplicação), possui os direitos necessários para registrar um pedido no sistema. E para isso você vai precisar ter um usuário cadastrado no sistema com os direitos necessários. Se tiver qualquer dúvida em como cadastrar este usuário, basta enviar um e-mail para o nosso time de suporte, ou com o consultor que atende sua empresa, e eles podem fazer isso por você.

Passo 3: Entendendo o serviço

Para cada pedido a ser enviado, sua aplicação precisará fazer um POST para o endpoint /daots (DAOT é a abreviação de "Documento Associado à Ordem de Transporte").

O corpo do request a ser enviado (payload) deve ter o seguinte formato:

{
  "tipo": 1,
  "emitente": {
    "cpfCnpj": {
      "tipoPessoa": 2,
      "numero": 01234567000099
    },
    "nome": "INDUSTRIA EMITENTE LTDA",
    "nomeFantasia": "EMITENTE",
    "endereco": {
      "logradouro": "RUA XPTO",
      "numero": 104,
      "complemento": "SALA 1042",
      "bairro": "PARQUE DO EMITENTE",
      "localidade": {
        "nome": "SAO PAULO",
        "uf": {
          "sigla": "SP"
        }
      },
      "cep": 12345678
    },
    "inscricaoEstadual": "847309874-Z",
    "inscricaoMunicipal": 2346143,
    "email": "expedicao@emitente.com.br",
    "contribuinte": true,
    "optanteSimples": false
  },
  "destinatario": {
    "cpfCnpj": {
      "tipoPessoa": 1,
      "numero": 98765432199
     },
    "nome": "MARIA DA SILVA",
    "nomeFantasia": null,
    "endereco": {
      "logradouro": "AV DO DESTINATARIO",
      "numero": 555,
      "complemento": null,
      "bairro": "CENTRO",
      "localidade": {
        "nome": "CURITIBA",
        "uf": {
          "sigla": "PR"
        }
      },
      "cep": 87654321
    },
    "inscricaoEstadual": "ISENTO",
    "inscricaoMunicipal": "ISENTO",
    "email": null,
    "contribuinte": false,
    "optanteSimples": false
  },
  "serie": 1,
  "numero": 404305,
  "emissao": "2023-04-04T00:00:00-00:00",
  "referencia": "K-324-54587-WP",
  "tipoMercadoria": "DIVERSOS",
  "tipoEmbalagem": "CX",
  "qtdVolumes": 6,
  "peso": 42.650,
  "volume": 4.2,
  "pesoCubado": 150.00,
  "valorMercadoria": 9945.06,
  "modalidadePagamento": 1,
  "unidade": {
    "sigla": "MTZ"
  }
}

Tipo

Código que identifica o tipo de documento que está sendo enviado. Pode ter os seguintes valores:

1 = Nota Fiscal
2 = Pedido
5 = Ordem de Coleta
6 = Solicitação de Transporte
10 = Declaração
11 = Documento de Importação
12 = DTA
9 = Outros

Emitente

Contém todos os dados necessários para o cadastramento do emitente do documento. Porém, caso tenha-se certeza de que o emitente já estará cadastrado no sistema, os detalhes podem ser emitidos, enviando apenas o atributo cpfCnpj.

Destinatário

Tem o mesmo formato do emitente, e da mesma forma pode ser enviado completo, caso deseje que o destinatário seja cadastrado automaticamente se não existir, ou apenas o seu cpfCnpj.

Série / Número / Emissão / Referência

Número e data de emissão do pedido (ou outro tipo de documento). Caso informado, o número de referência serve para associar o pedido à nota fiscal. Informando-se o mesmo número na tag xPed da NFe fará com que o sistema associe a nota fiscal e o pedido à mesma Ordem de Transporte.

Dados dos produtos

São os dados "preliminares" dos produtos a serem transportados, e só serão utilizados pelo sistema até que os dados "definitivos" sejam informados com a nota fiscal.

Tipo de mercadoria
Tipo da embalagem
Quantidade de volumes
Peso
Volume (em m3)
Peso cubado
Valor dos produtos

Modalidade de pagamento do frete

Código que identifica se o frete será CIF (1) ou FOB (2).

Unidade

Indica a qual unidade da empresa o pedido / Ordem de Transporte deve ser atribuído.

Retorno do serviço

O serviço irá retornar um JSON com todos os detalhes do pedido que foi importado. Você não precisa se preocupar com isso, a menos que deseje recuperar algum dado específico (por exemplo, você pode querer recuperar o ID da Ordem de Transporte que foi gerada no GL, para efetuar alguma outra integração posteriormente).

Abaixo um exemplo do retorno esperado:

{
  "documento": {...},
  "ot": {
    "id": ...,
    ...
  },
  "descricaoDocumento": "Pedido Nr. ..."
}

O único ponto que sua aplicação deve obrigatoriamente tratar é o código de retorno do processamento, que deve ser sempre 200 (OK). Qualquer valor diferente desse indica que houve um erro no processamento.

Passo 4. Confirmando que o pedido foi importado

Após executado o serviço acima, o pedido que você enviou já estará imediatamente disponível no GL. Você pode confirmar isso acessando o sistema, na página Operações -> Ordens. O pedido enviado deve ser exibido na lista (desde que atenda os filtros informados na página), e ali você poderá conferir todos os detalhes enviados.

Obtendo ajuda

Como dissemos no princípio, este não é um dos procedimentos dos mais fáceis 😬 .

Mas não se deixe intimidar! Com um pouco de paciência, e depois de entendidos os conceitos, não temos dúvidas que você terá sucesso 🥷, e o resultado vai valer a pena.

E lembre-se: Nosso time está à disposição para ajudá-lo a superar qualquer dificuldade, basta nos contatar no e-mail suporte@tecnovia.com.br.