Write-ahead log na persistência fiscal

O que é write-ahead log, em termos simples?

Write-ahead log, ou WAL, significa algo como registro antecipado de escrita. A ideia é anotar a intenção antes de agir: primeiro o sistema escreve em um diário seguro o que pretende fazer e só depois altera os dados principais.

Uma comparação útil é a de um caixa de loja que anota cada venda num caderno antes de mexer no estoque. Se faltar luz no meio do processo, basta consultar o caderno para saber o que já foi feito e o que ficou pendente.

Na persistência fiscal, ou seja, na forma como um sistema guarda informações sobre notas, eventos e protocolos, essa técnica ajuda a garantir que nada se perca entre o pedido de emissão e a resposta do fisco.

Por que o write-ahead log é importante na emissão fiscal?

Emitir um documento fiscal envolve várias etapas: montar o XML, assinar, enviar à SEFAZ ou à prefeitura, receber o protocolo e guardar o resultado. Uma falha no meio desse caminho pode deixar o sistema sem saber se a nota foi autorizada ou não.

Sem um registro confiável, o sistema pode reenviar a mesma nota e gerar duplicidade, pular uma numeração ou perder o XML autorizado, que precisa ser guardado. Com o WAL, o sistema sabe exatamente em que ponto parou e pode retomar dali com segurança.

Como funciona o write-ahead log na prática?

Antes de cada mudança importante, o sistema grava uma entrada no log, por exemplo: nota 1520 reservada, XML assinado, lote enviado, protocolo recebido. Essa gravação é feita de forma durável, isto é, confirmada em disco, e não apenas na memória.

Só depois dessa confirmação os dados principais são atualizados. Se houver uma queda, o processo de recuperação lê o log, refaz as etapas confirmadas que não chegaram aos dados principais e identifica as que ficaram incompletas, como um envio sem resposta, para consultar o status no fisco antes de agir.

Muitos bancos de dados já usam WAL internamente. Em integrações fiscais, a mesma lógica costuma aparecer também na aplicação, em tabelas de eventos ou filas que registram cada passo da emissão.

Qual a diferença entre write-ahead log, backup e log de auditoria?

O backup é uma cópia dos dados feita periodicamente para recuperar informações em caso de perda grave. O WAL atua continuamente, operação por operação, para manter os dados consistentes mesmo após uma falha repentina.

O log de auditoria, ou histórico de eventos fiscais, serve para mostrar quem fez o quê e quando, com foco em rastreabilidade. O WAL tem foco técnico: garantir que as operações sejam concluídas ou desfeitas corretamente. Os dois podem coexistir e até compartilhar informações, mas têm objetivos diferentes.

Como o write-ahead log se relaciona com idempotência e filas de emissão?

Idempotência é a capacidade de repetir uma requisição sem gerar um efeito duplicado. O WAL ajuda nisso porque registra que uma emissão já foi iniciada com determinada chave, permitindo que uma nova tentativa reconheça o trabalho já feito em vez de criar outra nota.

Em fluxos assíncronos, em que a nota entra numa fila e é processada depois, o log registra o estado de cada item. Assim, se o processador reiniciar, ele sabe quais documentos estão pendentes, quais aguardam retorno e quais já foram concluídos.

Quem precisa se preocupar com write-ahead log?

Equipes que desenvolvem ERPs, plataformas de venda ou marketplaces com emissão própria precisam pensar em como garantir a consistência dos dados em caso de falha. Quando a emissão é delegada a uma API fiscal, boa parte dessa responsabilidade fica com o emissor, mas o sistema do cliente ainda deve registrar seus pedidos de forma segura e usar chaves de idempotência para não perder nem duplicar solicitações.

Exemplos de Write-ahead log na persistência fiscal

• Um ERP grava no log que a NF-e de número 3050 foi enviada; o servidor reinicia antes de receber o protocolo e, ao voltar, o sistema consulta o status na SEFAZ em vez de reenviar a nota.
• Uma plataforma de serviços registra cada DPS da NFS-e no write-ahead log antes de chamar a API fiscal, conseguindo reprocessar apenas os pedidos que ficaram sem resposta após uma queda de rede.
• Um marketplace usa uma tabela de eventos no estilo WAL para acompanhar cada NFC-e do pedido até a autorização e o armazenamento do XML, evitando notas órfãs no banco.
• Uma transportadora registra no log a emissão de cada CT-e vinculado a um MDF-e, garantindo que o manifesto só seja encerrado quando todos os documentos estiverem confirmados.