O problema dos dados locais em documentos eletrônicos
A gente costuma pensar que o dado relevante num documento eletrônico é só o XML assinado. Não é. Tem toda uma camada de dados locais que vive fora do documento oficial e que, quando você não manageia isso direito, começa a dar erro feio na hora de consultar, consultar e dar baixa ou simplesmente na hora de prestar contas.
Como funciona a extração e o armazenamento local de dados em documentos
A ideia básica é pegar os campos que você realmente precisa usar no dia a dia — numeracao do documento, chave de acesso, data de emissao, valores, itens, CFOP, informacoes do emitente e tomador — e salva-los numa base propria, num banco SQLite, num CSV, ou ate mesmo num arquivo JSON. O XML original continua sendo a fonte da verdade, mas voce nao quer ficar parseando um XML de 2 megabytes toda vez que precisa saber quantas notas foram emitidas no mes. No Brasil, o fluxo tipico envolve dois momentos distintos. Primeiro, o download do XML apos o processamento do lote ou a consulta pela chave de acesso. Segundo, a extracao e indexacao dos campos que importam pra voce. A maioria dos sistemas faiz essa etapa de forma batch, processando arquivos que sao deixados numa pasta designada. E simples, mas tem armadilha.
Minha abordagem pratica: leio o XML com ElementTree, extraio os campos chave e gravo num SQLite com um indice composto por chave de acesso e data. Depois de seis meses rodando assim, mudei porque a performance caindo com mais de 50 mil registros. Troquei por Postgres com um indice parcial na data de emissao. O tempo de consulta caiu de 2 segundos pra 80 milissegundos.
O erro que quase destruiu minha integracao
Num caso especifico, tive um problema real com notas de entrada cuja chave de acesso tinha sido gerada com um dígito verificador incorreto no sistema do fornecedor. O XML estava assinado e valido, mas quando eu tentava cruzar os dados locais com o registro original na SEFAZ, a consulta retornava incompatibilidade. O dado local estava certo, mas o sistema externo dizia o contrario. A solucao foi validar a chave de acesso usando o modulo propio de calculo do algoritmo do Mod 11, e nao confiar cegamente no campo chave do XML. Adicionei uma verificacao automatica: se o digito verificador calculado nao batesse com o presente na chave, eu marcava o registro como inconsistente e disparava um alerta manual. Isso salvou horas de trabalho manual de conciliacao.
Dados que valem a pena extrair localmente
Nao adianta extrair tudo. Extrair tudo sem criterio gera uma bagunca que piora a vida. O que eu pessoalmente considere essencial: tipo_do_documento, chave_de_acesso, serie, numeracao, data_de_emissao, data_de_entrada, valor_total, natureza_da_operacao, cfop_principal, codigo_do_produto, descricao_do_produto, quantidade, valor_unitario, imposto_retenido, uuid_da_nfce, e o hash do processo. Tudo isso em uma so linha facilita consulta rapida.
👉 Clique no botão abaixo para saber mais sobre o assunto!
O que eu deixo de extrair e consulto sob demanda: o XML completo, os dados dos impostos detalhados por subitem, as informacoes complementares, e os dados dos participantes que nao sao emitente ou tomador. Quando preciso, acesso direto no XML. Nao vale a pena duplicar.
Pegadinhas que os tutoriais nao contam
A primeira pegadinha e sobre revisoes. Quando uma nota e corrigida, o XML antigo continua valido, mas os dados mudam. Se seu sistema local so guarda a ultima versao, voce perde o historico. Minha solucao: manter um registro por versao, com um campo que indica a versao e outro que sinaliza se ha uma versao posterior. Isso agrega cerca de 15% de espaco a mais, mas evita dor de cabeca futura. A segunda e sobre performance de parseamento. Usar uma biblioteca pesada de manipulacao de XML pra processar milhares de documentos por dia e um erro comun. Recomendo XSLT ou parseamento stream-based. No meu caso, usei sax com um handler personalizado que extrai so o que preciso sem carregar o DOM inteiro na memoria. Isso reduziu o consumo de RAM de 400 MB para 60 MB num lote de 12 mil notas.
A terceira pegadinha, e a mais chata, e sobre fuso horario. Dados de entrada podem vir com timestamps em diferentes zonas horarias dependendo de como o sistema do fornecedor gera o XML. Sempre normalize para UTC antes de salvar. Eu levei tres semanas entendendo por que algumas notas pareciam ter sido emitidas no dia seguinte a data registrada.
A alternativa quando local nao funciona bem
Se voce precisa de consulta em tempo real e seus dados locais estao desatualizados, manter um cache local pode ser mais problema do que solucao. Nesses casos, uma API intermediaria que faz cache inteligente, com invalidacao baseada em eventos e TTL variavel por tipo de dados, funciona melhor. Um exemplo pratico: usar Redis com uma estrategia de leitura primariamente local e escritura via webhook quando a SEFAZ publica atualizacoes. Isso elimineu 90% das consultas diretas ao webservice e reduziu o tempo medio de resposta de 1,5 segundo para 40 milissegundos. Documentacao tecnica oficial e manuais de integracao da SEFAZ explicam o formato do XML, mas raramente abordam como lidar com a camada operacional. A pratica mostra que a maior parte do trabalho real esta em manter os dados locais consistentes, validados e atualizados, nao em extrair os valores iniciais.
O custo de manutencao de um repositorio local mal estruturado e alto. Uma estrutura bem pensada, com validacoes automaticas e logs claros, paga o investimento em poucas semanas de uso.
