@treeunfe/cte

Biblioteca CT-e 4.00 (modelo 57) para Treeunfe DFe.

Funcionalidades

| Operação | Método adapter | Status | |----------|----------------|--------| | Status do serviço | ConsultaStatusServico() | Implementado | | Autorização síncrona | Autorizacao(cte, options?) | Implementado | | Contingência FS-DA (MG) | Autorizacao(cte, { transmitir: false }) | Implementado (MG only) | | Contingência SVC | Autorizacao(cte) com tpEmis=7 ou 8 | Implementado | | Contingência EPEC | AutorizacaoContingenciaEpec() / Epec() | Implementado | | Consulta protocolo | ConsultaProtocolo(chCTe) | Implementado | | Cancelamento (110111) | Cancelamento(data) | Implementado | | Carta de correção (110110) | CartaDeCorrecao(data) | Implementado | | DACTe PDF | GerarDACTe(props) | Implementado (MVP) | | DACCe PDF (CC-e CT-e) | GerarDACCe(props) | Implementado (auxiliar) | | Distribuição DFe | DistribuicaoDFe* | Implementado |

Escopo v1 (produto Treeunfe)

• CT-e modelo 57, tpCTe=0 (Normal)
• Modal rodoviário (01 / RNTRC)
• ICMS: CST 00, 20, 45, 60, 90
• IBSCBS opcional no builder
• DACTe retrato (Anexo II)
• Contingência FS-DA (tpEmis=5, MG only): emissão local + DACTe
• Contingência SVC (tpEmis=7/8): autorização direta na SVC-RS/SVC-SP
• Contingência EPEC (tpEmis=4): evento 110113 na SVC + regularização na origem

Contingência FS-DA (tpEmis=5) — apenas MG

Fluxo em duas etapas quando a SEFAZ está indisponível:

1. Emitir localmente (sem webservice) — monta XML assinado com dhCont + xJust, retorna procCTe sem protocolo:

const cte = {
  infCte: {
    ide: {
      tpEmis: '5',
      dhCont: '2026-08-28T12:00:00-03:00',
      xJust: 'Indisponibilidade do serviço de autorização da SEFAZ.',
      // ... demais campos do ide
    },
    // ...
  },
};

const local = await client.Autorizacao(cte, { transmitir: false });
await client.GerarDACTe({ procCTe: local.procCTe, outputPath: 'dacte-fsda.pdf' });

2. Regularizar na SEFAZ quando o serviço normalizar — reutilize o mesmo documento (mesma chave) com transmissão padrão:

const autorizado = await client.Autorizacao(cte); // transmitir=true (default)
await client.GerarDACTe({ procCTe: autorizado.procCTe, outputPath: 'dacte-autorizado.pdf' });

Campos obrigatórios em contingência: dhCont (data/hora da entrada) e xJust (15–256 caracteres).

NT 2024.001: FS-DA (tpEmis=5) permitido apenas para emitente MG (cUF=31). Demais UFs: use EPEC ou SVC.

Contingência SVC (tpEmis=7 ou 8 — conforme UF emitente)

Autorização direta na SEFAZ Virtual de Contingência. O tpEmis depende da UF do emitente (MOC CT-e 4.00):

| tpEmis | SVC | UFs emitentes | |--------|-----|---------------| | 7 | SVC-RS | AP, MT, MS, PE, RR, SP | | 8 | SVC-SP | Demais (incl. RS, MG, PR, SVRS…) |

Use resolveSvcContingenciaForUf(UF) de @treeunfe/shared:

import { resolveSvcContingenciaForUf } from '@treeunfe/shared';

const { tpEmis } = resolveSvcContingenciaForUf('RS'); // → '8' (SVC-SP)
const cte = {
  infCte: {
    ide: {
      tpEmis,
      dhCont: '2026-08-28T12:00:00-03:00',
      xJust: 'Indisponibilidade do serviço de autorização da SEFAZ.',
      // ...
    },
  },
};
const result = await client.Autorizacao(cte);

Antes de enviar, a lib consulta StatusServico na SEFAZ de origem e exige cStat=113 (SVC ativa). Em homologação, se retornar 107, prossegue com aviso. Use skipSvcActivationCheck: true para ignorar.

ConsultaProtocolo roteia automaticamente para a SVC quando tpEmis=7/8 na chave.

Contingência EPEC (tpEmis=4)

Fluxo two-phase — evento 110113 na SVC, depois CT na origem:

// Fase 1: evento EPEC + DACTe com protocolo EPEC
const epec = await client.AutorizacaoContingenciaEpec(cte, { fase: 'epec' });
await client.GerarDACTe({
  procCTe: epec.procCTe,
  nProtEpec: epec.nProtEpec,
  outputPath: 'dacte-epec.pdf',
});

// Fase 2: regularizar CT na SEFAZ origem (mesmo documento/chave)
// Retry automático aguardando sync SVC→origem (default 6×10s)
const autorizado = await client.AutorizacaoContingenciaEpec(cte, {
  fase: 'ct',
  epecRegularizacaoMaxTentativas: 12,
  epecRegularizacaoIntervaloMs: 15_000,
});

QR Code FS-DA/EPEC inclui &sign= (RSA-SHA1 da chave) conforme MOC §9.2.2.

Alternativa: Epec(payload) + Autorizacao(cte) separados.

CC-e e Cancelamento (eventos pós-autorização)

cOrgao: sempre o código IBGE da UF emitente (primeiros 2 dígitos da chCTe), inclusive para CT-e autorizado em SVC.

Roteamento de webservice (automático):

| Evento | tpEmis normal (1) | tpEmis SVC (7/8) | |--------|-------------------|------------------| | Cancelamento (110111) | SEFAZ origem | SVC (onde o CT-e foi autorizado) | | CC-e (110110) | SEFAZ origem | SEFAZ origem (SVC não recebe CC-e) |

Limitação SVC + CC-e: a SEFAZ de contingência (SVC) só aceita eventos EPEC, liberação EPEC e cancelamento. A CC-e deve ser enviada à SEFAZ de origem; se o CT-e ainda não constar na base da origem (cStat=217), aguarde a sincronização ou emita CC-e após retorno à emissão normal.

A CC-e CT-e exige xCondUso (literal Art. 58-B) — preenchido automaticamente via CTE_CCE_X_COND_USO de @treeunfe/shared.

// CC-e — após CT-e autorizado
const cce = await client.CartaDeCorrecao({
  chCTe,
  nSeqEvento: 1,
  infCorrecao: {
    grupo: 'compl',
    campo: 'xObs',
    valor: 'Texto corrigido conforme solicitacao.',
  },
  // CNPJ/CPF opcional — obtido do certificado se omitido
});
await persistProcEvento(cce.procEventoCTe);

await client.GerarDACCe({
  data: { xml: cce.procEventoCTe, emitente: dadosEmitente },
  outputPath: 'dacce-cte.pdf',
});

// Cancelamento — roteamento automático por chave
await client.Cancelamento({
  chCTe,
  nProt: protocoloAutorizacao,
  xJust: 'Justificativa com no minimo 15 caracteres.',
});

Integração backend (produção)

• Configure ambiente: 1 — URLs _P em CTeServicosUrl.json; não use skipSvcActivationCheck em produção.
• Persista procEventoCTe retornado por CartaDeCorrecao() / Cancelamento().
• PDF da CC-e é representação auxiliar (MOC não define layout oficial); a validade fiscal está no XML do evento.

Fora do escopo (fases futuras)

• CT-e OS (67), GTV-e (64), Simplificado
• Outros modais (aéreo, aquaviário, ferroviário, dutoviário, multimodal)
• tpCTe complementar/substituto/anulação
• PAA
• DACTe A5 / Ofício
• Eventos avançados (comprovante entrega, multimodal, etc.)

Documentação de referência

XSDs em runtime: packages/shared/resources/schemas/cte/

Consulte MOC CT-e 4.00 (Visão Geral, Anexo I leiaute, Anexo II DACTe) nos portais SEFAZ.

Exemplo / testes

Testes de execução na raiz do monorepo:

pnpm test:cte                              # autorização normal (RS)
CTE_SVC=1 pnpm test:cte                    # SVC (tpEmis auto: RS→8)
CTE_EPEC=1 pnpm test:cte                   # EPEC fase evento
CTE_EPEC_REGULARIZAR=1 pnpm test:cte       # EPEC regularização
CTE_CONTINGENCIA=1 CTE_UF=MG pnpm test:cte # FS-DA local (MG)
CTE_REGULARIZAR=1 CTE_UF=MG pnpm test:cte  # FS-DA regularizar (MG)
CTE_CCE=1 pnpm test:cte                    # CC-e no CT-e pendente
CTE_CANCEL=1 pnpm test:cte                 # Cancelamento no CT-e pendente

Trechos de código: examples/CTe/README.md

Notas

• Autorização usa CTeRecepcaoSincV4 (gzip+base64)
• Eventos usam XML sem compactação
• Inutilização não existe no CT-e 4.00 (eliminada pelo MOC)