# Write-ahead log na persistência fiscal

> Write-ahead log na persistência fiscal é a técnica de registrar, em um arquivo de diário durável, cada operação sobre um documento fiscal antes de executá-la ou gravá-la definitivamente. Assim, se o sistema cair no meio da emissão de uma NF-e ou NFS-e, é possível recuperar o estado correto, evitando perda de dados, duplicidade e inconsistências.

**Também conhecido como:** WAL, Write-ahead logging, Log de escrita antecipada, Registro antecipado de escrita, Journaling, Write-ahead log

**Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** W

## 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.

## Perguntas frequentes

### O write-ahead log substitui o backup?

Não. O WAL garante consistência após falhas repentinas, operação por operação. O backup protege contra perdas maiores, como corrupção de disco ou exclusão acidental. Os dois são complementares.

### O write-ahead log evita notas duplicadas?

Ajuda bastante. Ao registrar que uma emissão já começou, o sistema consegue verificar o status antes de reenviar. Para proteção completa, deve ser combinado com chaves de idempotência e consulta ao fisco.

### Preciso implementar WAL se uso um banco de dados moderno?

Muitos bancos já usam WAL internamente para suas próprias transações. Porém, etapas externas, como o envio à SEFAZ, não são cobertas por ele, por isso a aplicação também deve registrar o estado de cada emissão.

## Termos relacionados

- [Idempotência na emissão fiscal](https://conota.dev/glossario/idempotencia-na-emissao-fiscal.md)
- [Fila de emissão fiscal](https://conota.dev/glossario/fila-de-emissao-fiscal.md)
- [Fluxo assíncrono de emissão](https://conota.dev/glossario/fluxo-assincrono-de-emissao.md)
- [Duplicidade de NF-e](https://conota.dev/glossario/duplicidade-de-nf-e.md)
- [Histórico de eventos fiscais](https://conota.dev/glossario/historico-de-eventos-fiscais.md)
- [Guarda de documentos fiscais](https://conota.dev/glossario/guarda-de-documentos-fiscais.md)

---

Fonte: [Write-ahead log na persistência fiscal](https://conota.dev/glossario/write-ahead-log-na-persistencia-fiscal/) · Atualizado em 2026-10-22