Agora no Bluesoft ERP, é possível consultar, obter arquivos em Base64, importar e processar Conhecimentos de Transporte Eletrônicos (CT-e) diretamente via API. Com a criação desses novos endpoints, as integrações externas podem interagir com o fluxo de CT-e sem a necessidade de operação manual na interface do sistema.

Objetivo

O objetivo desta melhoria é automatizar e dar maior autonomia às integrações sistêmicas, permitindo que toda a rotina de recepção e análise de CT-es ocorra em segundo plano. Isso elimina gargalos operacionais, reduz a necessidade de intervenção humana na expedição/recebimento e aumenta a resiliência na comunicação de dados com sistemas externos.

O Que Mudou?

Como Era o Processo Antes?

Antes, Bluesoft ERP já disponibilizava funcionalidades para consulta, importação e processamento de CT-es por meio da tela Estoques e NF-e > Conhecimento de Transporte > Processamento CT-e, além das rotinas automatizadas existentes de recepção e processamento de documentos.. Porém, a integração externa não possuía cobertura completa de API para reproduzir esse fluxo sistêmico.

Agora, com os novos endpoints, a integração tem autonomia total para gerir a entrada de CT-es, reaproveitando as mesmas regras de validação e processamento já existentes na tela do ERP.

Benefícios:

  • Automação: permite que sistemas externos consultem e importem XMLs de CT-e por API.
  • Agilidade operacional: reduz a necessidade de intervenção manual nas operações de consulta e envio de documentos.
  • Integração: facilita a comunicação entre o ERP e outras aplicações que utilizam informações de transporte.
  • Acompanhamento: permite consultar posteriormente as informações e o status de processamento dos CT-es registrados no ERP.

Como Irá Funcionar a Partir de Agora?

Foram disponibilizados três novos endpoints:

1. Consultar Processamento CT-e (GET /api/estoque/processamento-cte)

  • Permite consultar os CT-es na base do ERP de forma paginada e sem duplicidades (retornando um único registro por CT-e, mesmo com várias NF-e vinculadas).
  • A busca pode ser feita pela chaveCte de forma direta (dispensando outros filtros), ou preenchendo as chaves obrigatórias de período: lojaKey, tipoPeriodo (IMPORTACAO ou EMISSAO), dataInicial e dataFinal.

2. Obter XML Processamento CT-e (GET /api/estoque/processamento-cte/obter-xml)

  • Permite recuperar o conteúdo XML de um CT-e registrado no ERP.
  • Ao realizar a busca informando a chaveCte, o sistema validará a disponibilidade do arquivo e retornará exclusivamente o XML correspondente, codificado no formato Base64.
  • Caso a chave não seja encontrada ou o XML esteja indisponível, a solicitação será bloqueada com a respectiva indicação de erro.

3. Importar XML Processamento CT-e (POST /api/estoque/processamento-cte)

Permite enviar um XML de CT-e codificado em Base64 para importação no ERP, com a possibilidade de solicitar seu processamento.

Na requisição, devem ser informados:

  • xmlBase64: conteúdo do XML do CT-e codificado em Base64.
  • processarXml: campo booleano que determina se o processamento será solicitado após a importação.
Comportamento do campo processarXml:
  • true: importa o XML e solicita seu processamento por meio da rotina assíncrona existente.
  • false: realiza somente a importação, mantendo o CT-e disponível para processamento posterior.

Quando a requisição é aceita, a API retorna a chave do CT-e (cteKey), o status inicial da solicitação e uma mensagem de confirmação.

Importante: o retorno de sucesso confirma o aceite da importação e seu encaminhamento ao fluxo correspondente. Isso não significa que todas as validações e etapas do processamento fiscal tenham sido concluídas.

Notificações por webhook

A importação também permite configurar uma URL para receber notificações relacionadas ao fluxo de importação do documento. O campo urlNotificacao é opcional. Quando não informado, nenhuma notificação é solicitada.

Para configurar a autenticação do callback, estão disponíveis as opções:

  • DESABILITADO: não utiliza header configurável de autenticação.
  • HEADER: utiliza um header de autenticação, exigindo os campos nomeDoHeader e token.

Atenção: a notificação não deve ser interpretada como garantia de conclusão do processamento fiscal. Para confirmar a situação do CT-e, utilize a API de consulta de processamento.

Observações Importantes!

  • Permissões de Acesso: A nova funcionalidade de integração é controlada por permissões específicas. Para executar as rotas, o usuário/token da API precisa possuir as permissões:
    • 4145 - API Processador CT-e (Consultar)
    • 4144 - API Processador CT-e (Executar).
  • Regras de Centro de Resultado: A API respeita as regras de negócio vigentes. Se a configuração de Centro de Resultado for obrigatória nas movimentações contábeis, o sistema apenas importará o XML (mesmo que processarXml seja enviado como true), e o CT-e ficará com status Pendente, exigindo a definição manual do rateio antes da conclusão do processamento.
  • Status do Processamento: O retorno de sucesso e o disparo do callback de importação confirmam o recebimento do CT-e e o envio para a fila de processamento automático. O resultado definitivo do processamento da nota deverá ser consultado posteriormente via API, utilizando a cteKey retornada.

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 r374.03