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.

Existem várias maneiras para que as NFes sejam importadas no GL, entre elas:

Importação automática do Portal Nacional da NFe (disponível apenas para NFes de terceiros, e não do próprio emitente);
Importação manual, através da página de Ordens de Transporte do Gestor Logístico;
Envio através de e-mail, para o endereço nfe.sua-empresa@gestorlogistico.com.br (este processo precisa ser previamente configurado pelo time da Tecnovia);
Envio através de SFTP para o servidor da Tecnovia;
Copiando os arquivos em um diretório local (em algum computador no seu próprio ambiente), e utilizando um utilitário da Tecnovia para fazer o envio;
ou, finalmente, através da API do Gestor Logístico, que é a forma que vamos descrever neste artigo.

Como fazer

Vamos a um "passo a passo":

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 uma Nota Fiscal 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 nota fiscal a ser enviada, sua aplicação precisará fazer um POST para o endpoint /nfes/xml, enviando no payload o XML da nota. O XML deve ser enviado no corpo do payload, como uma "string", no atributo "xml". Segue um exemplo:

POST /nfes/xml
header: "Authorization": "Basic ..."
header: "Content-Type": "application/json"
{
 "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc versao=\"4.00\" xmlns=\"http://www.portalfiscal.inf.br/nfe\"><NFe xmlns=\"http://www.portalfiscal.inf.br/nfe\">...</NFe><protNFe versao=\"4.00\">...</protNFe></nfeProc>"
}

obs: Lembre-se que, neste caso, como o XML vai ser enviado entre aspas ("), o conteúdo deve ser tratado para "escapar" as aspas contidas no XML (\").

O serviço irá retornar um JSON com todos os detalhes da Nota Fiscal que foi importada, tanto dados que estavam no corpo do XML, quanto outros que o sistema vai gerar internamente. 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": "Nota fiscal 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 a nota fiscal foi importada

Após executado o serviço acima, a nota fiscal que você enviou já estará imediatamente disponível no GL. Você pode confirmar isso acessando o sistema, na página Operações -> Ordens. Sua nota fiscal deve ser exibida 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.