Desmistificando a Automação Fiscal no Backend (CT-e, MDF-e e CIOT)

Emitir um CT-e ou um MDF-e parece simples: montar um XML, assinar e enviar. Na prática, você depende de webservices governamentais (SEFAZ) e, no caso do CIOT, de integradoras logísticas que oscilam, ficam lentas e saem do ar justamente nos horários de pico. Neste artigo vou mostrar a arquitetura que uso para lidar com isso em C# / .NET: emissão assíncrona com filas, validação antes do envio, armazenamento seguro de certificado e comunicação resiliente.

A premissa de tudo é uma só: o serviço externo vai falhar. A pergunta é se o seu sistema está preparado para isso.


O problema de emitir na requisição HTTP

O erro mais comum é emitir o documento dentro da requisição do usuário. Se a SEFAZ demorar 40 segundos para responder:

  • a API fica presa esperando e consome threads e conexões;
  • o usuário acha que travou e clica de novo;
  • você corre o risco de emitir o mesmo documento em duplicidade;
  • um timeout deixa o sistema sem saber se o documento foi autorizado ou não.

A solução é desacoplar o pedido de emissão da emissão em si.


Emissão assíncrona com filas

O fluxo recomendado:

  1. A API recebe a solicitação, valida, persiste o documento com status Pendente e registra uma mensagem de saída (outbox) na mesma transação.
  2. Um relay publica a mensagem no broker (RabbitMQ, Azure Service Bus, SQS...).
  3. Um worker consome a mensagem, monta o XML, assina, envia e atualiza o status.
  4. O front acompanha o status por polling, WebSocket ou SignalR.
// API: responde rápido, sem esperar a SEFAZ
app.MapPost("/cte", async (
    EmitirCteRequest request,
    IValidator<EmitirCteRequest> validator,
    AppDbContext db,
    CancellationToken ct) =>
{
    var validacao = await validator.ValidateAsync(request, ct);
    if (!validacao.IsValid)
        return Results.ValidationProblem(validacao.ToDictionary());

    var cte = Cte.Criar(request);
    db.Ctes.Add(cte);

    // Outbox: a mensagem só existe se o CT-e for salvo (mesma transação)
    db.Outbox.Add(OutboxMessage.Criar("cte.emitir", new { cte.Id }));

    await db.SaveChangesAsync(ct);

    return Results.Accepted($"/cte/{cte.Id}", new { cte.Id, cte.Status });
});

O 202 Accepted comunica corretamente o que aconteceu: o pedido foi aceito, mas o processamento ainda não terminou. O SaveChangesAsync do EF Core executa as duas inserções em uma única transação.

Máquina de estados do documento

Trate o documento como uma máquina de estados explícita. Isso facilita o suporte e impede transições inválidas:

Pendente → Enviando → Autorizado
                   ↘ Rejeitado
                   ↘ ErroTemporario → (retry) → Enviando
Autorizado → Cancelado | Encerrado (MDF-e)
public enum StatusDocumento { Pendente, Enviando, Autorizado, Rejeitado, ErroTemporario, Cancelado, Encerrado }

public class Cte
{
    private static readonly Dictionary<StatusDocumento, StatusDocumento[]> Transicoes = new()
    {
        [StatusDocumento.Pendente]        = [StatusDocumento.Enviando],
        [StatusDocumento.Enviando]        = [StatusDocumento.Autorizado, StatusDocumento.Rejeitado, StatusDocumento.ErroTemporario],
        [StatusDocumento.ErroTemporario]  = [StatusDocumento.Enviando],
        [StatusDocumento.Autorizado]      = [StatusDocumento.Cancelado],
    };

    public Guid Id { get; private set; }
    public StatusDocumento Status { get; private set; }
    public string? ChaveAcesso { get; private set; }
    public List<HistoricoStatus> Historico { get; } = [];

    public void Transicionar(StatusDocumento novo, string? motivo = null)
    {
        if (!Transicoes.TryGetValue(Status, out var permitidos) || !permitidos.Contains(novo))
            throw new InvalidOperationException($"Transição inválida: {Status} → {novo}");

        Historico.Add(new HistoricoStatus(Status, novo, motivo, DateTimeOffset.UtcNow));
        Status = novo;
    }
}

Cada transição fica registrada com data e motivo. Esse histórico é valioso quando alguém pergunta "por que esse CT-e ainda está pendente?".

Outbox pattern

Sem ele, existe uma janela de falha: o registro é salvo, mas a aplicação cai antes de publicar na fila (ou publica e o commit falha). Com a tabela Outbox, a mensagem é gravada na mesma transação do documento, e um processo separado a publica no broker. Você passa a ter garantia de entrega "pelo menos uma vez" e resolve o resto com idempotência.

public sealed class OutboxRelay(IServiceScopeFactory scopes, ILogger<OutboxRelay> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(1));

        while (await timer.WaitForNextTickAsync(ct))
        {
            using var scope = scopes.CreateScope();
            var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
            var publisher = scope.ServiceProvider.GetRequiredService<IMessagePublisher>();

            var pendentes = await db.Outbox
                .Where(m => m.PublicadoEm == null)
                .OrderBy(m => m.CriadoEm)
                .Take(50)
                .ToListAsync(ct);

            foreach (var msg in pendentes)
            {
                try
                {
                    await publisher.PublicarAsync(msg.Topico, msg.Payload, ct);
                    msg.PublicadoEm = DateTimeOffset.UtcNow;
                }
                catch (Exception ex)
                {
                    logger.LogWarning(ex, "Falha ao publicar mensagem {Id}", msg.Id);
                    break; // preserva a ordem e tenta no próximo ciclo
                }
            }

            await db.SaveChangesAsync(ct);
        }
    }
}

Bibliotecas como MassTransit e Wolverine trazem implementações prontas de outbox para o EF Core. Avalie as licenças e escolha conforme o seu contexto.

Idempotência

Como a entrega é "pelo menos uma vez", o worker pode receber a mesma mensagem duas vezes. Por isso:

  • a chave de acesso (44 dígitos) identifica o documento de forma única;
  • antes de reenviar, o worker consulta a situação do documento na SEFAZ;
  • o estado atual no banco é verificado antes de qualquer ação (se já está Autorizado, a mensagem é descartada).
public sealed class EmitirCteHandler(
    AppDbContext db,
    ISefazClient sefaz,
    IValidadorCte validador,
    EmissorCte emissor)
{
    public async Task HandleAsync(Guid cteId, CancellationToken ct)
    {
        var cte = await db.Ctes.FindAsync([cteId], ct) ?? throw new KeyNotFoundException();

        if (cte.Status is StatusDocumento.Autorizado or StatusDocumento.Rejeitado)
            return; // idempotência: já foi resolvido

        // Pode ter sido processado numa tentativa anterior que deu timeout
        if (cte.ChaveAcesso is not null)
        {
            var situacao = await sefaz.ConsultarSituacaoAsync(cte.ChaveAcesso, ct);
            if (situacao.Autorizado)
            {
                cte.Transicionar(StatusDocumento.Autorizado, situacao.Protocolo);
                await db.SaveChangesAsync(ct);
                return;
            }
        }

        cte.Transicionar(StatusDocumento.Enviando);
        await db.SaveChangesAsync(ct);

        await emissor.EmitirAsync(cte, ct);
    }
}

Retry, backoff e DLQ

  • Retry com backoff exponencial (e jitter) para erros transitórios: timeout, 5xx, falha de conexão.
  • Dead-letter queue (DLQ) para mensagens que esgotaram as tentativas, com alerta para a operação.
  • Separação de erros: erro de rede é retentável; rejeição fiscal (o documento tem um problema) não é. Retentar uma rejeição só gera ruído e pode até gerar bloqueio por excesso de requisições.

Uma forma de deixar essa separação explícita é usar exceções distintas:

public sealed class RejeicaoFiscalException(int codigo, string motivo) : Exception(motivo)
{
    public int Codigo { get; } = codigo; // não retentar: o documento precisa ser corrigido
}

public sealed class FalhaTransitoriaException(string mensagem, Exception? inner = null) : Exception(mensagem, inner);

No consumidor, FalhaTransitoriaException volta para a fila com backoff, enquanto RejeicaoFiscalException marca o documento como Rejeitado e notifica o usuário, sem retentativa.


Validar antes de chamar o webservice

Cada chamada à SEFAZ custa tempo, e uma rejeição só chega depois de todo o ciclo de rede. Validar localmente antes de enviar reduz rejeições e dá feedback imediato ao usuário. Eu separo em camadas:

  1. Validação de entrada (FluentValidation): tipos, obrigatoriedade e formatos básicos, ainda na API.
  2. Validação de schema (XSD): o XML precisa estar de acordo com o layout oficial da versão vigente.
  3. Validação de regras de negócio: CNPJ/CPF válidos, placa e RNTRC preenchidos, totais de carga coerentes, documentos vinculados ao MDF-e já autorizados e outras regras do manual de orientação do contribuinte.
  4. Validação de pré-requisitos: certificado válido e não vencido, série e numeração disponíveis, emitente habilitado.

Camada 1: entrada com FluentValidation

public sealed class EmitirCteRequestValidator : AbstractValidator<EmitirCteRequest>
{
    public EmitirCteRequestValidator()
    {
        RuleFor(x => x.Emitente.Cnpj).Must(Cnpj.EhValido).WithMessage("CNPJ do emitente inválido");
        RuleFor(x => x.ValorTotal).GreaterThan(0).WithMessage("Valor total deve ser maior que zero");
        RuleFor(x => x.Veiculo.Placa).Matches("^[A-Z]{3}[0-9][A-Z0-9][0-9]{2}$");
        RuleFor(x => x.Veiculo.Rntrc).NotEmpty();
    }
}

Camada 2: validação do XML contra o XSD

public sealed class ValidadorXsd
{
    private readonly XmlSchemaSet _schemas = new();

    public ValidadorXsd(string pastaSchemas, string namespaceAlvo, string arquivoPrincipal)
    {
        _schemas.Add(namespaceAlvo, Path.Combine(pastaSchemas, arquivoPrincipal));
        _schemas.Compile();
    }

    public IReadOnlyList<string> Validar(string xml)
    {
        var erros = new List<string>();

        var settings = new XmlReaderSettings
        {
            ValidationType = ValidationType.Schema,
            Schemas = _schemas,
            DtdProcessing = DtdProcessing.Prohibit, // evita ataques via DTD/XXE
        };
        settings.ValidationEventHandler += (_, e) =>
            erros.Add($"Linha {e.Exception.LineNumber}: {e.Message}");

        using var reader = XmlReader.Create(new StringReader(xml), settings);
        while (reader.Read()) { /* a leitura completa dispara a validação */ }

        return erros;
    }
}

Juntando as camadas

public sealed class ValidadorCte(ValidadorXsd xsd, ICertificadoService certificados) : IValidadorCte
{
    public async Task<string> ValidarAntesDeEnviarAsync(Cte cte, CancellationToken ct)
    {
        var erros = new List<string>();

        var certificado = await certificados.ObterAsync(cte.EmitenteId, ct);
        if (certificado.NotAfter <= DateTime.Now)
            erros.Add("Certificado digital vencido");

        var xml = GeradorXmlCte.Gerar(cte);
        erros.AddRange(xsd.Validar(xml));

        if (erros.Count > 0)
            throw new ValidacaoFiscalException(erros);

        return xml;
    }
}

Documentos que falham aqui nunca chegam à fila de envio. Eles voltam ao usuário com uma mensagem clara e em linguagem de negócio, e não com um código de rejeição crítico.

Dois detalhes práticos:

  • Versione os schemas XSD e as regras. O governo publica notas técnicas com frequência, e você precisa conseguir atualizar sem quebrar o histórico.
  • Mantenha as regras de validação testáveis, com uma suíte de casos reais de rejeição que você já viu em produção.

Armazenamento seguro de certificado digital

O certificado A1 (.pfx) com sua senha é uma credencial extremamente sensível: quem o possui assina documentos fiscais em nome da empresa. Regras que sigo:

  • Nunca armazenar o arquivo ou a senha em texto puro, nem em appsettings.json versionado.
  • Criptografar com AES-256-GCM, que garante confidencialidade e integridade.
  • Usar envelope encryption: cada certificado é cifrado com uma data key, e essa chave é protegida por uma chave mestra em um KMS (Azure Key Vault, AWS KMS, GCP KMS, HashiCorp Vault).
  • Guardar separadamente o arquivo cifrado e a senha cifrada.
  • Descriptografar apenas em memória, no momento da assinatura, sem gravar em disco nem em log.
  • Restringir quem pode acessar a chave no KMS (princípio do menor privilégio) e auditar cada uso.
  • Monitorar a data de validade e alertar o cliente com antecedência, porque certificado vencido significa operação parada.
public sealed record CertificadoCifrado(
    byte[] Conteudo, byte[] Nonce, byte[] Tag, byte[] DataKeyCifrada);

public sealed class CofreCertificados(IKms kms)
{
    public async Task<CertificadoCifrado> ProtegerAsync(byte[] pfx, CancellationToken ct)
    {
        var dataKey = RandomNumberGenerator.GetBytes(32);                       // AES-256
        var nonce   = RandomNumberGenerator.GetBytes(AesGcm.NonceByteSizes.MaxSize); // 12 bytes
        var tag     = new byte[AesGcm.TagByteSizes.MaxSize];                    // 16 bytes
        var cifrado = new byte[pfx.Length];

        try
        {
            using var aes = new AesGcm(dataKey, tag.Length);
            aes.Encrypt(nonce, pfx, cifrado, tag);

            // A data key só é guardada cifrada pela chave mestra do KMS
            var dataKeyCifrada = await kms.CifrarAsync(dataKey, ct);
            return new CertificadoCifrado(cifrado, nonce, tag, dataKeyCifrada);
        }
        finally
        {
            CryptographicOperations.ZeroMemory(dataKey);
        }
    }

    public async Task<X509Certificate2> CarregarAsync(
        CertificadoCifrado protegido, string senha, CancellationToken ct)
    {
        var dataKey = await kms.DecifrarAsync(protegido.DataKeyCifrada, ct);
        var pfx = new byte[protegido.Conteudo.Length];

        try
        {
            using var aes = new AesGcm(dataKey, protegido.Tag.Length);
            aes.Decrypt(protegido.Nonce, protegido.Conteudo, protegido.Tag, pfx); // falha se adulterado

            // EphemeralKeySet: a chave privada não é gravada em disco
            return new X509Certificate2(pfx, senha, X509KeyStorageFlags.EphemeralKeySet);
        }
        finally
        {
            CryptographicOperations.ZeroMemory(dataKey);
            CryptographicOperations.ZeroMemory(pfx);
        }
    }
}

Observações:

  • No .NET 9, prefira X509CertificateLoader.LoadPkcs12(...), pois o construtor de X509Certificate2 para dados PKCS#12 foi marcado como obsoleto.
  • O EphemeralKeySet não é suportado em todas as plataformas (por exemplo, macOS). Confirme no seu ambiente de execução.
  • Em ambientes multi-tenant, isole por cliente: cada empresa com sua própria data key. O vazamento de uma chave não compromete as demais.
  • Evite manter o certificado carregado por mais tempo que o necessário. Se o custo de carregar for um problema, use um cache de curta duração e restrito ao processo.

Assinatura do XML

public static class AssinadorXml
{
    public static XmlDocument Assinar(XmlDocument doc, string idElemento, X509Certificate2 certificado)
    {
        var signedXml = new SignedXml(doc) { SigningKey = certificado.GetRSAPrivateKey() };

        var reference = new Reference($"#{idElemento}");
        reference.AddTransform(new XmlDsigEnvelopedSignatureTransform());
        reference.AddTransform(new XmlDsigC14NTransform());
        // Ajuste DigestMethod e SignatureMethod conforme o manual do documento
        signedXml.AddReference(reference);

        signedXml.KeyInfo = new KeyInfo();
        signedXml.KeyInfo.AddClause(new KeyInfoX509Data(certificado));

        signedXml.ComputeSignature();
        doc.DocumentElement!.AppendChild(doc.ImportNode(signedXml.GetXml(), true));
        return doc;
    }
}

Os algoritmos de assinatura e de digest exigidos variam conforme o documento e a versão do layout. Siga sempre o manual de orientação do contribuinte vigente.


Comunicação resiliente com webservices

  • Timeouts explícitos em toda chamada externa. O padrão de muitas bibliotecas é esperar por muito tempo.
  • Circuit breaker: se a SEFAZ de um estado está instável, pare de bombardeá-la e tente novamente depois. Isso protege o seu sistema e o serviço deles.
  • Rate limiting no consumo da fila: limite a vazão do worker por UF/serviço para não ser bloqueado.
  • Contingência: conheça os modos previstos para cada documento (como SVC para CT-e e contingência offline para MDF-e) e deixe a decisão de ativá-los explícita e auditável.
  • Consulta de recibo/protocolo: nunca assuma que "deu timeout" significa "não emitiu". A SEFAZ pode ter processado. Consulte antes de reenviar.
  • Auditoria: guarde o XML enviado, a resposta e os timestamps. Quando houver um problema fiscal, esse histórico é a sua defesa.

No .NET, o pacote Microsoft.Extensions.Http.Resilience (baseado no Polly v8) configura timeout, retry e circuit breaker direto no HttpClient:

builder.Services
    .AddHttpClient<ISefazClient, SefazClient>(client =>
    {
        client.BaseAddress = new Uri(builder.Configuration["Sefaz:BaseUrl"]!);
    })
    .ConfigurePrimaryHttpMessageHandler(sp => new SocketsHttpHandler
    {
        PooledConnectionLifetime = TimeSpan.FromMinutes(5),
        // SSL = new SslClientAuthenticationOptions { ClientCertificates = ... } // TLS mútuo exigido pela SEFAZ
    })
    .AddStandardResilienceHandler(o =>
    {
        o.AttemptTimeout.Timeout        = TimeSpan.FromSeconds(30);
        o.TotalRequestTimeout.Timeout   = TimeSpan.FromSeconds(90);

        o.Retry.MaxRetryAttempts = 3;
        o.Retry.BackoffType      = DelayBackoffType.Exponential;
        o.Retry.UseJitter        = true;
        // Não retentar POST às cegas: antes de reenviar, consulte a situação do documento
        o.Retry.DisableForUnsafeHttpMethods();

        o.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(60);
        o.CircuitBreaker.FailureRatio     = 0.5;
        o.CircuitBreaker.MinimumThroughput = 10;
        o.CircuitBreaker.BreakDuration    = TimeSpan.FromSeconds(30);
    });

Repare em DisableForUnsafeHttpMethods(): o envio de um documento é um POST que não é idempotente do ponto de vista do HTTP. A estratégia segura é deixar a retentativa a cargo do worker, que consulta a situação antes de enviar novamente, e não de um retry automático e cego do cliente HTTP.

Integradoras de CIOT

A integração com o CIOT segue a mesma lógica, mas com particularidades: cada integradora tem sua própria API, seus limites e seus formatos. Por isso, vale a pena criar uma camada de abstração (adapter):

public interface IProvedorCiot
{
    Task<ResultadoCiot> EmitirAsync(DadosCiot dados, CancellationToken ct);
    Task<ResultadoCiot> ConsultarAsync(string codigo, CancellationToken ct);
    Task EncerrarAsync(string codigo, CancellationToken ct);
}

// Seleção do provedor por empresa/contrato
public sealed class ProvedorCiotFactory(IServiceProvider sp)
{
    public IProvedorCiot Obter(string integradora) =>
        sp.GetRequiredKeyedService<IProvedorCiot>(integradora);
}

Assim, trocar de integradora (ou suportar várias ao mesmo tempo) não contamina o domínio, e o circuit breaker e os retries ficam centralizados em cada adapter.


Observabilidade

Sem visibilidade, a automação fiscal vira uma caixa-preta. O mínimo que acompanho:

  • Métricas: taxa de autorização, de rejeição e de erro por UF; tempo médio de resposta da SEFAZ; tamanho da fila; mensagens na DLQ.
  • Logs estruturados com ChaveAcesso e DocumentoId como correlação (sem dados sensíveis).
  • Alertas para fila crescendo, pico de rejeições e certificados próximos do vencimento.
  • Painel de status por documento, com histórico de transições, para o suporte resolver sem abrir chamado para o time de desenvolvimento.
using (logger.BeginScope(new Dictionary<string, object>
{
    ["DocumentoId"]  = cte.Id,
    ["ChaveAcesso"]  = cte.ChaveAcesso ?? "",
}))
{
    logger.LogInformation("Enviando CT-e para a SEFAZ {Uf}", cte.UfEmitente);
    // ...
}

Com OpenTelemetry (AddOpenTelemetry().WithTracing(...).WithMetrics(...)), você propaga o trace da requisição original até o worker e consegue acompanhar um documento de ponta a ponta. Os health checks (AddHealthChecks()) ajudam a sinalizar degradação do banco, do broker e do certificado.


Conclusão

Automação fiscal não é sobre montar o XML, é sobre tratar a falha como regra. Filas e outbox desacoplam a emissão da requisição; validação prévia evita viagens inúteis à SEFAZ; idempotência e consulta de protocolo evitam duplicidade; criptografia em envelope protege o ativo mais crítico; e observabilidade mostra o que está acontecendo. Com essas peças, o webservice instável deixa de ser um problema do usuário e passa a ser apenas um detalhe de infraestrutura.