Importando CTes via API

O CT-e (Conhecimento de Transporte eletrônico) é o documento fiscal emitido pela transportadora para cada frete. Quando o Gestor Logístico recebe o XML de um CT-e, ele cria (ou atualiza) o DT (Documento de Transporte) correspondente — a peça central usada na auditoria de fretes, no controle de prazos e nos relatórios gerenciais. Este artigo mostra como automatizar esse recebimento via API, em vez de fazer o upload manual do XML pela tela a cada CT-e emitido.

Formas de enviar o CT-e ao Gestor Logístico

Importação automática pelo Portal Nacional do CT-e;
Envio por e-mail ou SFTP para o servidor da Tecnovia — ver Recebendo e tratando os CTes das transportadoras;
Upload manual do XML pela tela de CTes da transportadora — ver Importando os CTes;
API do Gestor Logístico (foco deste artigo) — indicada quando o sistema da transportadora (ou um hub de EDI intermediário) já consegue disparar uma chamada HTTP assim que o CT-e é autorizado na Sefaz.

Antes de começar

Entenda os princípios da API do GL — formato de dados, autenticação e URLs — no artigo Implementando integrações via API, se ainda não tiver feito nenhuma integração com o Gestor Logístico.
Peça as credenciais — é necessário um usuário cadastrado no sistema com o direito de importar DTs liberado para integração via API. Fale com o suporte (e-mail abaixo) ou com o consultor responsável pela sua conta para ter esse usuário criado e o direito atribuído.

Como funciona o serviço

Diferente da API de importação de NF-e (que aceita o XML como texto dentro do corpo JSON), a de CT-e recebe o arquivo XML por upload, no formato multipart/form-data — um arquivo por chamada.

Endpoint:

POST /importacao-arquivos/dts Content-Type: multipart/form-data

Corpo da requisição: o arquivo XML do CT-e autorizado, anexado como o arquivo do formulário (o mesmo XML que a Sefaz devolve na autorização, sem compactação).

Atenção — não é o mesmo formato da API de NF-e.
Se sua integração já envia NF-e via API, não reaproveite o payload JSON com o XML escapado em uma string — a de CT-e espera o arquivo em upload multipart. Enviar um JSON com xml como string neste endpoint não funciona.

Retorno esperado: como um único arquivo pode trazer mais de um CT-e ou evento, a resposta é sempre uma lista — um item por DT processado (ou por erro individual, se algum dos CTes do arquivo não puder ser importado):

[
   {
     "dt": {
       "id": 123456,
       "numeroFormatado": "...",
       "...": "..."     },
       "descricaoDocumento": "DT Nr. ..."   
   }
]

Se algum CT-e do arquivo já tiver sido importado antes, ou tiver erro de validação, o item correspondente na lista traz msgErro preenchido em vez de dt — trate cada item da lista individualmente, não assuma que a chamada inteira falhou só porque um dos itens teve problema.

Se preferir registrar o arquivo em duas etapas (por exemplo, quando o XML já está hospedado e você só quer apontar a URL) em vez de enviar o upload diretamente, existe um caminho alternativo de duas chamadas — fale com o suporte para os detalhes desse fluxo, que é mais indicado para volumes altos ou arquiteturas que já centralizam arquivos antes de processá-los.

Confirmando a importação

Assim que a chamada retornar com sucesso, o DT já está disponível no Gestor Logístico. Verifique pelo menu Operações → CTes (transportadora) ou na tela de Documentos de Transporte, conforme os filtros aplicados.

Dica: comece testando com um único XML de CT-e antes de automatizar o envio em lote — assim você confirma que o direito do usuário de integração está liberado e que o retorno está sendo tratado corretamente (inclusive o caso de item com msgErro) antes de colocar o fluxo em produção.

Obtendo ajuda

Como em qualquer integração via API, é normal levar um tempo até dominar os detalhes — formato do XML, tratamento de erros por item da lista, reenvio em caso de falha. Nossa equipe de suporte pode ajudar em cada etapa.

Veja também

Dúvidas?

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