Endpoints CT-e
Emitir, transmitir à SEFAZ, DACTE PDF, XML, cancelar e debug.
Referência técnica completa de todos os endpoints REST para emissão, envio, consulta, cancelamento e depuração de CT-e (Conhecimento de Transporte Eletrônico - Modelo 57). Todos os endpoints exigem autenticação via header X-API-Key.
Endpoints Disponíveis
/v1/cteCria um rascunho de CT-e com dados do frete, percurso, carga e participantes.
/v1/cte/:id/sendEnfileira o CT-e para assinatura digital A1 e autorização junto à SEFAZ via fila assíncrona.
/v1/cte/:idConsulta o status, chave de acesso de 44 dígitos, protocolo e dados completos do CT-e.
/v1/cte/:id/dacteGera e faz o download do DACTE em formato PDF com código de barras e QR Code oficial.
/v1/cte/:id/xmlObtém o XML assinado ou autorizado com protocolo da SEFAZ (Content-Type: application/xml).
/v1/cte/:id/cancelCancela um CT-e autorizado transmitindo o evento de cancelamento oficial à SEFAZ.
/v1/cte/:id/cceEmite Carta de Correção Eletrônica (CC-e tpEvento 110110) para sanar dados cadastrais ou observações.
/v1/cte/inutilizarInutiliza faixa numérica de CT-e (Modelo 57) quebrada perante o webservice CteInutilizacao da SEFAZ.
/v1/cte/:id/debugObtém auditoria técnica completa: payload JSON original, logs de fila, status SOAP, eventos e XML.
/v1/cteLista conhecimentos de transporte emitidos com suporte a filtros e paginação.
/v1/cte/:idExclui um CT-e em estado de rascunho ou erro pré-transmissão.
1. Criar Rascunho de CT-e (POST /v1/cte)
Crie o documento com os dados do transporte. A numeração sequencial e a série são reservadas automaticamente com base nas configurações da sua empresa.
O body JSON permite definir remetente, destinatário, percurso (início e término), valor da prestação, componentes de frete, dados do veículo e NF-es transportadas.
/v1/cteDica
customerId para reaproveitar os dados cadastrais e endereço automaticamente.2. Transmitir à SEFAZ (POST /v1/cte/:id/send)
Dispara o processo de autorização assíncrona. O worker do NFER assina o XML com o Certificado Digital A1, conecta ao webservice SOAP da SEFAZ e obtém o protocolo de autorização (cStat 100).
/v1/cte/:id/sendA API responde imediatamente confirmando o enfileiramento na fila de alta velocidade. Você pode acompanhar o status via polling no endpoint GET /v1/cte/:id ou consultar o modal de debug.
3. Consultar CT-e (GET /v1/cte/:id)
Retorna os dados completos do CT-e, incluindo situação na SEFAZ, chave de acesso de 44 dígitos e protocolo de autorização.
4. DACTE em PDF (GET /v1/cte/:id/dacte)
Retorna o fluxo binário do PDF do DACTE com cabeçalho Content-Type: application/pdf. O documento é cacheado no storage seguro da NFER para recuperação instantânea.
Parâmetros opcionais de Query String:
download=true: Adiciona cabeçalhoContent-Disposition: attachmentpara forçar download no navegador.regenerate=true: Ignora o cache do S3 e regera o PDF com layout atualizado.
5. Obter XML Autorizado (GET /v1/cte/:id/xml)
Retorna o XML completo com as tags <CTe> e <protCTe> autorizados pela SEFAZ. Ideal para envio automatizado a tomadores, contabilidade ou arquivamento fiscal.
6. Cancelar CT-e (POST /v1/cte/:id/cancel)
Cancela o Conhecimento de Transporte perante a SEFAZ. O cancelamento exige que a viagem de transporte ainda não tenha sido iniciada e respeite o prazo regulamentar da SEFAZ estadual (geralmente até 7 dias da autorização).
A justificativa deve ser clara e conter no mínimo 15 caracteres e no máximo 255 caracteres.
/v1/cte/:id/cancel7. Carta de Correção Eletrônica - CC-e (POST /v1/cte/:id/cce)
Emite o evento oficial de Carta de Correção de CT-e (tpEvento 110110) conforme o Art. 58-B do CONVÊNIO/SINIEF 06/89. Permite corrigir erros cadastrais e observações do transporte. É vedada a alteração de valores de imposto, alíquotas, dados cadastrais que impliquem mudança de remetente/destinatário/tomador ou datas de emissão.
Você pode enviar a correção como texto livre (mínimo 15 caracteres) ou como array de nós estruturados no grupo correcoes.
/v1/cte/:id/cce8. Inutilização de Numeração (POST /v1/cte/inutilizar)
Comunica a quebra de sequência numérica de CT-e (Modelo 57) diretamente ao webservice CteInutilizacao da SEFAZ, garantindo conformidade com a obrigação legal de justificar números não utilizados até o 10º dia do mês subsequente.
Informe a série, o número inicial e final do intervalo a inutilizar e uma justificativa detalhada com pelo menos 15 caracteres.
/v1/cte/inutilizar9. Depuração Completa (GET /v1/cte/:id/debug)
Inspeciona a auditoria profunda do documento: payload JSON original recebido pela API, histórico cronológico de logs da fila SEFAZ com códigos de resposta (cStat, xMotivo), eventos de CC-e vinculados, XML assinado/transmitido e snapshot do banco de dados.