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:
- A API recebe a solicitação, valida, persiste o documento com status
Pendentee registra uma mensagem de saída (outbox) na mesma transação. - Um relay publica a mensagem no broker (RabbitMQ, Azure Service Bus, SQS...).
- Um worker consome a mensagem, monta o XML, assina, envia e atualiza o status.
- 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:
- Validação de entrada (FluentValidation): tipos, obrigatoriedade e formatos básicos, ainda na API.
- Validação de schema (XSD): o XML precisa estar de acordo com o layout oficial da versão vigente.
- 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.
- 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.jsonversionado. - 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 deX509Certificate2para dados PKCS#12 foi marcado como obsoleto. - O
EphemeralKeySetnã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
ChaveAcessoeDocumentoIdcomo 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.