Biblioteca fiscal do GitHub: como saber se ela acompanha o leiaute antes da rejeição

O Mercado Bom Preço emite nota com uma biblioteca open source que entrou no projeto em 2018 e "sempre funcionou". Na primeira semana de um mês, uma nota técnica passa a valer em produção, e as notas começam a voltar rejeitadas no dia de maior movimento. Alguém abre o repositório da biblioteca: último commit há catorze meses, três issues abertas pedindo justamente aquela nota técnica. A resposta curta: biblioteca fiscal não acompanha o leiaute sozinha, e o risco de ela parar é seu. Saiba que versão você usa, olhe a saúde do projeto antes de cada mudança anunciada, teste em homologação antes da data de produção e tenha plano para quando o mantenedor sumir.

Bibliotecas como as do ecossistema ACBr, e tantas outras no GitHub, poupam meses de trabalho. O problema não é usar, é usar sem acompanhar. Este guia é sobre esse acompanhamento. A questão de responsabilidade fiscal, que a biblioteca também não assume, está em biblioteca de nota fiscal não substitui o contador.

Por que a biblioteca envelhece mais rápido que o resto do sistema

Uma biblioteca de JSON pode ficar anos sem mudança e continuar correta, porque o formato não muda. Uma biblioteca fiscal implementa uma especificação que muda várias vezes por ano:

• Notas técnicas acrescentam campos, mudam regras de validação e criam grupos, mesmo sem trocar o número da versão do leiaute.
• Pacotes de schemas são republicados, e a biblioteca precisa trazer os novos.
• Endereços de serviço e certificados dos autorizadores mudam, e a biblioteca que traz uma lista fixa de URLs fica para trás.
• A reforma tributária do consumo trouxe grupos novos para IBS e CBS, com cronograma próprio, o que aumenta o volume de mudança nos próximos anos.

Cada uma dessas mudanças tem data para entrar em produção. Se a biblioteca não acompanha até lá, o seu sistema emite o leiaute do ano passado e a Sefaz recusa.

Como medir a saúde do projeto em cinco minutos

Com o gh, a CLI do GitHub, dá para responder às perguntas que importam sem abrir o navegador. Troque ORGANIZACAO/biblioteca-nfe pelo repositório que você usa:

# o repositório está arquivado? quando recebeu o último push?
gh api repos/ORGANIZACAO/biblioteca-nfe --jq '{arquivado: .archived, ultimo_push: .pushed_at}'

# as últimas versões publicadas
gh release list -R ORGANIZACAO/biblioteca-nfe --limit 5

# alguém já pediu a nota técnica que vai entrar em vigor?
gh issue list -R ORGANIZACAO/biblioteca-nfe --search "nota técnica" --state open

E no seu projeto .NET, a versão que você usa e se há mais nova:

dotnet list package --outdated

Se a biblioteca foi copiada para dentro do repositório em vez de vir de um gerenciador de pacotes, descubra quando ela foi tocada pela última vez:

git log -1 --format=%cs -- libs/fiscal/

Leia o resultado assim: push recente e issues de nota técnica respondidas indicam projeto vivo. Último push há mais de um ano, issues de nota técnica sem resposta ou repositório arquivado indicam que a próxima mudança vai cair no seu colo.

Como manter a biblioteca alinhada com o leiaute

1. Fixe a versão. No arquivo de projeto, uma versão exata, não um intervalo. Atualizar biblioteca fiscal é decisão, não efeito colateral de um build.
2. Registre o alinhamento. Versão da biblioteca, versão do leiaute, última nota técnica que ela cobre e data do último teste em homologação. Uma ficha no repositório basta; o guia de conferir o leiaute que vale hoje tem um modelo.
3. Acompanhe as notas técnicas no Portal Nacional da NF-e. Para cada uma, anote a data de produção e cruze com a ficha.
4. Atualize em homologação semanas antes da data. Atualize a biblioteca num branch, rode os testes, emita em homologação os cenários reais da empresa: venda simples, devolução, cliente de outro estado, cancelamento.
5. Tenha um teste automatizado de leiaute. Uma nota de referência gerada pelo seu sistema precisa passar no schema mais recente guardado no repositório.
6. Isole a biblioteca atrás de uma interface sua. O resto do sistema chama IEmissorFiscal, não as classes da biblioteca. Trocar de biblioteca vira trocar uma implementação.

O teste que avisa quando o schema muda

Usando a função de validação mostrada no guia de XML da nota sem concatenar:

public class LeiauteTests
{
    [Fact]
    public void Nota_de_referencia_passa_no_schema_mais_recente()
    {
        var nota = NotaDeReferencia.GerarAssinadaComCertificadoDeTeste();
        var erros = ValidadorFiscal.ValidarNota(nota, Path.Combine("schemas", "nfe"));
        Assert.Empty(erros);
    }
}

Quando alguém atualiza a pasta schemas com o pacote novo do portal, o teste quebra se a biblioteca ainda gera o leiaute antigo. A quebra aparece no CI, numa terça qualquer, e não no caixa.

Quando o projeto parou

Se a análise mostrou um projeto abandonado, você tem três caminhos, e nenhum deles é "esperar":

• Assumir a manutenção, num fork seu, com alguém da equipe responsável por implementar cada nota técnica. É viável se o código é bom e a equipe entende o leiaute. Fork sem dono, criado para um ajuste e esquecido, é o pior dos mundos.
• Trocar por outra biblioteca mantida, com plano: implementação nova atrás da mesma interface, testes de leiaute, período em homologação, troca numa data calma.
• Contratar um serviço ou componente comercial com contrato de atualização. Leia o que o contrato garante sobre prazos de nota técnica e redistribuição; o guia de licença de componente fiscal fala disso.

Erros comuns

• Não saber qual versão da biblioteca está em produção. Na hora da rejeição, ninguém sabe se a correção já existe.
• Atualizar a biblioteca no dia em que a nota técnica entra em produção. Sem homologação, a atualização pode quebrar outra coisa, e você descobre no caixa.
• Usar intervalo de versão no gerenciador de pacotes. Um build qualquer traz uma versão nova que ninguém testou.
• Fazer fork para um ajuste e esquecer. O fork para de receber as correções do original e não recebe as suas.
• Espalhar chamadas da biblioteca pelo sistema todo. Trocar de biblioteca vira reescrever metade do sistema.
• Confiar no "sempre funcionou". Funcionou para o leiaute de antes. A especificação mudou, a biblioteca não.

Checklist

• A versão exata da biblioteca fiscal em produção está fixada e registrada.
• Você sabe a data do último push e da última versão publicada do projeto.
• As notas técnicas com data futura estão listadas e cruzadas com o que a biblioteca cobre.
• Cada atualização passa por homologação com os cenários reais da empresa antes de ir para produção.
• Existe um teste automatizado que valida uma nota de referência contra o schema mais recente.
• O sistema fala com a biblioteca por uma interface própria.
• Há um plano escrito para o caso de o projeto parar.

Rode agora o primeiro comando deste guia no repositório da biblioteca que emite a sua nota: qual é a data do último push, e ela é anterior à última nota técnica publicada?