Agora no Bluesoft ERP, é possível obter o arquivo XML de um Conhecimento de Transporte Eletrônico (CT-e) via API, utilizando apenas a chave de acesso do documento, através de uma nova rota dedicada exclusivamente para esta finalidade.

O objetivo desta melhoria é facilitar a integração de dados para sistemas externos, garantindo que o integrador possua uma rota pública, padronizada e segura para baixar o XML do documento de transporte vinculado às notas fiscais de entrada.

O Que Mudou?

Antes, o sistema possuía apenas a API de consulta para XML de Notas Fiscais (NF-e). Quando um integrador conseguia identificar a chave de um CT-e vinculado a uma nota de entrada, ele não possuía uma rota pública disponível para realizar o download do XML desse documento logístico, limitando o consumo de dados na integração externa.

Agora, foi criada uma rota exclusiva para a consulta de CT-e, evitando qualquer ambiguidade com as chaves de notas fiscais. Ao consultar a chave de um CT-e importado no ERP, o sistema gera e retorna uma URL temporária para que o integrador realize o download direto do arquivo já formatado com a extensão .xml.

  • Benefício: Autonomia para integrações externas, separação clara de contratos entre NF-e e CT-e, e agilidade no acesso aos dados do documento de transporte.

Como Irá Funcionar a Partir de Agora?

  1. O integrador deverá realizar uma requisição do tipo GET para a nova rota: /api/estoques/ctes/xml/{cteChave}.
  2. No parâmetro de caminho {cteChave}, deve ser informada a chave de acesso do CT-e, que deve conter exatamente 44 caracteres puramente numéricos.
  3. O sistema localizará o CT-e no banco de dados e, confirmando a existência do arquivo no armazenamento, retornará um objeto JSON contendo o campo URL_S3.
  4. O integrador utilizará o link recebido no campo URL_S3 para realizar o download automático do arquivo XML do CT-e correspondente.

Observações Importantes!

  • Permissões de Acesso: Para acessar a nova rota, o usuário da API precisará ter a nova permissão específica habilitada: 4700 – API – CT-es (Consultar). A permissão antiga de notas fiscais (3950) não concede acesso a esta rota.
  • Validade da URL: A URL gerada e retornada no campo URL_S3 é temporária e possui validade de 1 minuto. Após este prazo, o link expira e o acesso ao download retorna AccessDenied, sendo necessário gerar uma nova consulta.
  • Validação de Chave: O sistema rejeitará requisições caso a chave contenha letras, espaços, caracteres especiais ou tenha um tamanho diferente de 44 dígitos.
  • Independência de Status: A API retornará o XML independentemente do status principal de processamento do CT-e no ERP, desde que o arquivo já esteja importado e disponível no armazenamento (S3).
  • Comportamento Legado: A API já existente de XML da NF-e (/api/estoques/notas-fiscais/xml/{nfChave}) permanece sem nenhuma alteração de comportamento ou de contrato.

Para conhecer mais sobre como é a utilização dessa ferramenta, clique aqui.

Para saber mais sobre a utilização das APIs do ERP, clique aqui.

Disponível a partir da versão r372.01